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Preface 





Our design philosophy for the Turbo Pascal Program Library is easily stated: “Make 
ita programming companion. Create a reference for repeated use.” Contained in 
these pages is a comprehensive library of practical Turbo Pascal subprograms (pro- 
cedures and functions). 


At first glance, it may seem odd that our program library is composed of subpro- 
grams, not programs. The reason is that Pascal encourages a modular programming 
style in which most of a program’s detailed tasks are delegated to subprograms, 
The subprograms are then assimilated into the full program to form one cohesive 
unit, 


This book is a library of subprograms that are meant to be building blocks toward 
your finished programs. Think of these subprograms as the foundation stones on 
which your programming construction projects are built, Whether your undertaking 
is simple or complex, you should find in this book useful components that will 
save you time and trouble. 


Is this book for you? If you program in Turbo Pascal, the answer is yes. By taking 
advantage of our ready-made routines, you can improve your productivity imme- 
diately. The first time you use one of these subprograms, you should be able to 
justify the cost of the book in the hours you save by not having to develop original 
code, And if you use any of our complete programs, your savings are even greater, 


If you are an intermediate or advanced programmer, think of this book as an instant 
software reference library. For you, its primary benefits are simplified program de- 
velopment and expediency. If you are a beginner in Pascal, you receive the additional 
benefit of practical program components you might otherwise be unable to develop 
yourself, 

We assume that you know how to program in Pascal, at least rudimentarily. ‘This 
book is neither a tutorial on Pascal in general nor a tutorial on Turbo Pascal in 
particular. (Many excellent books that teach these subjects are available.) At a 
minimum, you should know how to get Pascal running on your computer, type a 
program, save it on disk, compile the program, and run it 


xv 


Even if you are just beginning to learn Pascal (especially if you are a “learn by 
doing” person), this book will be a useful companion. We explain many program- 
ming tips and techniques throughout the presentation of these subprograms, Ad- 
ditionally, the exposure to well-structured, useful subprograms and full programs 
will help you understand more than just the rules of Pascal. Pascal encourages 4 
clean, structured, top-down programming style, and we have tried to exemplify it. 
We hope this book will help you become a more knowledgeable programmer. 
Our target audience is the largest group of Turbo Pascal users—those with IBM 
PCs or compatibles. However, those who use Turbo Pascal on other computers 
(CP/M® computers, Apple®, etc. ) should find the subprograms helpful, as will users 
of other versions of Pascal. You may have to make some changes, though, to enable 
certain programs to work 
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How To Use This Book 


The Structure of a Pascal Program 


‘We can view a Pascal program as consisting of three sections. Let's call section 1 
the “global declarations section,” section 2 the “subprograms section,” and section 
3 the “mainline logic section.” The word subprograms is Pascal terminology for 
the program components that comprise procedures and functions. Here is a “pseu- 
doprogram” with numbers at the right to indicate the sections: 





program MainProgram, a) 
(global declarations for MainProgram and) a) 
{all subprograms, ? a) 

function FunctionA; (2) 
(local declarations and logic of FunctionA) 2) 

function FunctionB; (2) 
(local declarations and logic of FunctionB) @ 

procedure ProcedureA; (2) 
(local declarations and logic of ProcedureA) (2) 

procedure ProcedureB; @ 
{local declarations and logic of ProcedureB) @ 

BEGIN @) 
Clogic of MainProgram) @ 

END, 3) 


Most authorities recommend that the mainline logic section be short. Rather than 
perform all the detailed logic of the program in the mainline section, you should 
design individual chunks of logic called subprograms and put them in the subpro: 
grams section. Then your mainline logic section can simply invoke each subprogram 
to do its work as necessary. This method of organization simplifies the processes 
of designing and testing the program, thus improving productivity. 
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We strongly endorse this programming approach, That’s why the Turbo Pascal 
Program Library contains subprograms, not programs. Think of this book as a library 
for constructing programs, not as a library of programs. 


AL one time or another, most programmers find themselves caught in the “rein- 
vention of the wheel” syndrome. This typically happens during the writing of sub- 
programs, At one of these frustrating moments, have you ever asked yourself, “I 
bet someone has written a subprogram to do this before. Why can't I just borrow 
theirs and save myself some time and trouble?" Well, that’s our cue. 


The Program Library Concept 
‘The Turbo Pascal Program Library contains over 100 useful subprograms designed 
to give you the “wheels” so that you can concentrate on your mainline logic. You 
ean choose subprograms to enter data from the keyboard, detect errors, produce 
graphics effects, manipulate disk files, sort data, calculate curve fits, do matrix al- 
gebra, and accomplish many other useful tasks. 


Each subprogram has been used in “real world” full programs and has shown its 
practical value under firing-line conditions. Chapter 18 presents 10 full programs 
that demonstrate how easy it is to assimilate the subprograms. More than 40 of 
the subprograms in this book are used in those full programs. 






HOW TO USE THIS BOOK 3 





The Assimilation Process 


‘Once you have a subprogram saved on disk, you can easily incorporate the sub- 
Program into your main program. You can do this in two ways. For each method, 
Wwe assume that you're composing a main program with the Turbo editor. 


The first method is to create a complete source copy of the subprogram in your 
main program. To do this while using the Turbo editor, you position the cursor 
where you want the subprogram to appear. Then you press Ctrl-K (press and hold 
down the Ctrl key while you press also the K key) followed by the R key. This 
sequence causes the Turbo editor to prompt you for the name of a disk file to be 
read into your main program. You simply give the name of the subprogram you 
want. A complete copy of the subprogram appears at the cursor location. 


‘The second method is to use Turbo's ($1) compiler directive. You include just 


‘one line in the subprograms section of your program, The syntax for the compiler 
directive is 


(SI Filename) 


in which the file name will be one of your subprogram names, The ($1) directive 
tells the compiler to include the subprogeam within your main program at compile 
time. This approach saves considerable space in your program listings. The full 
programs in Chapter 18 are good examples of this method. 


A Disk Offer for Lazy Typists 


‘Typing annoys many programmers—especially typing “canned” code from a book 
like ours. Because we don't want any undue suffering, we've put all the source 
code from this book onto disk software for the IBM® PC and compatibles, Included 
are all the subprograms, Sample Usage programs, and full programs found in the 
book. When you use this software, typing hassles will fade into distant memory. 
See the disk offer at the back of the book. 


Hardware and Software Configurations 


All the programs and subprograms in this book were developed with Turbo Pascal® 
Version 3,01A on a standard IBM PC running under DOS V2.0. A dual floppy disk 
system is assumed with at least 128K of RAM (random-access memory). See Ap- 
pendixes A and D. 
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Documenting the Subprograms 


Each subprogram is accompanied by a detailed explanation, designed to help you 
decide whether the subprogram fits your particular needs and how to take full 
advantage of it when it does. We've standardized the form of these write-ups, creat- 
ing a “template” for each subprogram explanation. This template consists of the 
following parts. 


A Quicklook Box 


This handy “quick reference” box, providing a thumbnail description of the sub- 
program, contains the following: 

Name (the full name of the subprogram) 

‘Type (procedure or function) 

Purpose (a brief explanation of what it does) 

Calling Sequence (the parameters passed) 
‘The Name is the unique, descriptive name we have assigned to the subprogram. 
‘The name can contain up to eight characters. For example, the subprogram 


GetReply 


gets a reply from the keyboard. Capitalization is used in the subprogram name for 
clarity but is ignored by DOS and Turbo. When saving the subprogram to disk, we 
add the extension .PSL (for Pascal Subprogram Library; these subprograms, the 
Sample Usage programs, and the full programs make up the Turbo Pascal Program 
Library), PSL is always in uppercase. Thus, GetReply is saved on disk as 


GetReply. PSL 


‘The Type indicates whether the subprogram is a procedure or a function. If the 
Subprogram is a function, the kind of function is also given, such as a real function, 
an integer function, a boolean function, and so on. 


‘The Calling Sequence shows the exact syntax you use to invoke the subprogram 
from your main program. This information enables you to see at a glance the pa- 
rameters required to use the subprogram. For example, the Calling Sequence for 
GetReply is 


GetReply(First, Last, Reply) 
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Description 


This section contains a one-paragraph explanation of what the subprogram does 
and when it might be used. 


Input 


The Input section describes everything required by the calling routine before the 
subprogram can be called. This section usually contains a list of the parameters 
(variable names) that must be passed to the subprogram so that it can perform its 
intended function. The three-column list contains the variable name, the variable 
type, and a short description of what the variable does and how to use it, Note 
that you do not need to use the same variable names as ours, but your type dec- 
laration for each variable must be the same as ours. 


Sometimes a subprogram has other requirements, such as a global variable or a 
type declaration that needs to be defined, another subprogram that must be called 
first, or a specific state to which the computer must be set (high-resolution graphics 
mode, for example). When global variables or type declarations are required, you 
must use the same names we use, unless you modify the subprograms’ names (0 
match your global names. 


Output 


Similar to the Input section, Output describes the output expected from the sub- 
program. This section includes the variables set and the actions performed. 


Limitations and Error Conditions 


‘This section contains the limitations of the subprogram, any error conditions it 
detects, and the actions the subprogram takes when encountering an error, 


Sample Usage 
To illustrate the use of each subprogram, we've included a short sample program 
that contains the subprogram presented. This Sample Usage program assimilates 
the subprogram, using the ($1) compiler directive explained previously. You can 


type this sample program and run it to test the subprogram, but you first must 
have on disk a copy of the subprogram with the correct name. 


‘Typically, the output of the Sample Usage program is shown also, illustrating how 
the program works and demonstrating the use of the included subprogram. 





6 TURBO PASCAL PROGRAM LIBRARY 





Subprogram Listing 
‘This is a complete listing of the Turbo Pascal source code for the subprogram. The 
listing is printed on a shaded background for easy reference. 


Variables 


All the variables defined inside the subprogram are listed, along with explanations 
of their uses. These variables are local to the subprograms (and any embedded 
blocks) and are not defined at the level of the main program. 


Discussion 


‘This section contains information to help you make effective use of the subprogram, 
This section may include cross-references to other subprograms; applications that 
may not be obvious; theoretical foundations; details about the programming 
techniques used; and information about speed, memory use, or other resource 
requirements. 


Modifications 


Sometimes you want a subprogram to work slightly differently. In this section are 
specific changes you can make in the subprogram's source code so that you can 
tailor the subprogram to your exact needs. 


Style Conventions 


‘There are no rigid rules covering the “correct” way to write a Pascal program. Each 
programmer has a unique style for capitalization, indentation, identifier names, etc. 
Our approach and recommendations are covered in detail in Appendix C. 


How To Get Started 


If you are a grizzled Turbo Pascal veteran, you probably know exactly how you 
want to enter and run these subprograms, and how you'll add them to your existing 
subprogram library. For those who would like some advice on how to get started, 
refer to Appendix A. There you'll find recommendations about entering and testing 
Me eabexonrais fixing typing errors, building a subprogram library, and solving 
problems. 





Getting Keyboard Input 





Computer programs aren't very useful without data on which to operate, and nearly 
all data is input from the keyboard at one time or another. This chapter provides 
nine subprograms to aid you in constructing programs that require use of the 
keyboard. 

GetReply, GetKey, and KeyHit are useful when your program requires detection of 
a single key pressed. GetReply is designed to get a reply within a specified con- 
secutive range, such as after displaying a menu of options from 1 through 5, GetKey 
detects any keystroke that you indicate to be allowable, whether consecutive or 
not. KeyHit retrieves a key that has been pressed, if any, without causing your 
program to pause, All three subprograms require only a single keystroke; you don’t 
need to press the Enter key afterward. 


‘You should use GetNunR or GetNual in programs that call for entry of a numeric 
value. Turbo Pascal aborts your program with a run-time error if you accidentally 
type an illegal character when a readin procedure requests a numerie variable. 
‘These two subprograms avoid this problem. Use GetNumR for real variables, and 
GetNunl for integer variables. 








Uni tKey displays a message and waits for a key to be pressed before the program 
continues. This simple procedure is often needed in programs. 


Finally, this chapter has three subprograms for filling arrays with data entered from 
the keyboard. KeyArr is designed for entry of data into 4 one-dimensional real 
array. With a simple modification, you can use Key@rr for an integer array instead. 
Key2Arr is for entering data into a two-dimensional real array, and KeyTxt is for 
keying text data into a string array 
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GetReply 
Name: GetReply 
‘Type: Procedure 
Purpose: To detect a keystroke within a specified range 
Calling Sequence: GetReply(First, Last, Reply) 














Description 
GetReply first prompts you to enter a reply (press a key) and then displays both 
the first and the last key of the acceptable range. You may specify the range to be 
whatever you want, Other replies are ignored. When you press a key, its value is 
returned in Reply. 


Input 
First char In ASCII sequence the lowest key that is an 
acceptable reply 
Last char In ASCII sequence the highest key that is an 
acceptable reply 
Output 
Reply char The key you press 


‘The subprogram prompts you to Enter reply from (First to CLast]. and waits 
for you to press an acceptable key. 


Limitations and Error Conditions 


First and Last are displayed in ascending ASCII sequence, even when you specify 
them in descending order. If the two are equal, then only that one key satisfies the 
condition. Note that alphabetic ranges are sensitive to upper- and lowercase. For 
instance, if you specify the range from ‘A to “G’, you are requiring uppercase 
entries, whereas ‘a’ to’ g’ requires lowercase entries. You can specify the entire 
“normal” keyboard (that is, not counting special-function keys, such as Fl through 
F10, Home, Del, etc.) as acceptable entries by using the range of ‘’ (a blank 
space) to ‘2’. Special-function keys that cause a two-byte result (“Escape” plus a 
code) cause Reply to be set to zero. Thus, these keys are ignored unless you set 
First or Last to a value of chr(@). Note that the subprogram does not display the 
key pressed. Your main program must display the reply if that is what you want. 
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Sample Usage 
Program Samp]eUsageOfGetReply; 


var 
First, Last, Reply: char; 


($1 GetReply. PSL) 


BEGIN 
First = °1, 
last = '5; 
GetReply(First, Last, Reply); 
uriteln(’ Reply = ‘, Reply); 
GatReply('2', “AW, Reply); 
uriteln(’ Second reply =’, Reply) 
END. 


This sample program produces the following output on the screen if you press the 
3 key after the first prompt, and the Z key after the second prompt: 





Enter reply from 1 to 5. 
Reply = 3 

Enter reply from A to Z. 
Second reply = Z 


Subprogram Listing of GetReply.PSL 
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Variables 
Temp ‘Temporary char variable used in interchanging First and 
Last, if necessary 
Discussion 


GetReply has two common uses. First, you can retrieve a reply to a menu of choices. 
Such choices are generally labeled 1 through 5, or A through K, or some other 
consecutive range of values. (If your choices are not consecutive, see GetKey.) Your 
mainline program can then use Pascal's case statement to take appropriate action 
depending on which Reply you get. The second common use arises when your 
program displays a screenful of data and has more to come. You can ask for a key 
to be pressed to continue with the display or, if a special key is pressed, to take 
some other action. GetReply (unlike Turbo’s builtin keypressed procedure) en- 
ables you to see which key was pressed. When using GetReply in this second way, 
you will want to replace its prompting message with one of your own to indicate 
the choices. In some cases, GetKey will be a more appropriate subprogram. 


Modifications 


None 


GetKey 





Name: GetKey 
Type: Procedure 
Purpose: To detect a keystroke from an eligible list 
Calling Sequence: GetKey(KeyList, Reply, Reply) 
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Description 


GetKey detects which key is pressed from a list of eligible keys you specify in 
KeyList. No prompting message is shown, and the key pressed is not echoed on 
the screen. If you make KeyList the null string (two consecutive apostrophes with 
no space between them), then any key is accepted. When the Esc (Escape) key 
(#27, or ASCII decimal 27) is included in the list, the special-function keys (F1 
through F10, Home, Del, etc.) are allowable replies. When you press a special- 
function key, Reply returns #27 (Escape), and Reply2 returns the value of the key 
as shown in Appendix K of the Turbo Pascal Reference Manual. if you don't include 
the Esc key in the list (or imply the Esc key with a null KeyList), then Reply 
contains the key value, and Reply2 is #0. If the Esc key itself is pressed, Reply is 
#27, and Reply? is #0. 


‘Typical uses of this subprogram are to detect when a key is pressed without re- 
quiring the Enter key to be pressed afterward, and to require one key from a limited 
list to be pressed, but no other keys. This second use is common if you want 
someone to press Y or N (for yes or no) in response to your message but want 
to ignore any other replies 





Input 


KeyList string List of allowable keys to press. If null, any key is 
allowable. 


‘You must also specify the following global type declaration in your main program, 
‘The string length of 10 is an example. 


‘type 
KeyListType = stringC103, 


‘The string needs to be only as long as KeyList but must be at least 1 


Output 
Reply char The value of the key pressed. For special-function 
keys, Reply has the value #27. 
Reply2 char ‘The second value for a special-function key (see 


Appendix K of the Turbo manual), or #0 otherwise 


Limitations and Error Conditions 


Upper- and lowercase keys are differentiated. If, for example, you want both Y and 
y to be allowable keys, you must include both in KeyList. 
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Sample Usage 
program SampleUsage0fGetKey; 
type 
KeyListType = stringli3, 
var 
KeyList + KeyListType; 
Reply, Reply2 * char, 
(SI GetKey. PSL) 
‘BEGIN 


uriteln(’ Press ¥ for yes or N for no’); 
GetKay(’ YyNn’, Reply, Reply2); 
uriteln(Reply); 
uriteln( Press any key’); 
KayList «= ’’; (null string - no spaces betuaen apostrophes? 
GetKey(KeyList, Reply, Reply2); 
writeln(ord(Reply):4, ord(Reply2):4) 
END, 





This sample program produces the following output on the screen if you press the 


Y key after the first prompt (it ignores all other keys except y, N, and n), and the 
FI specialfunction key after the second prompt: 





Prass Y for yes or N for no 
Y 
Press any key 

7 9 
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Subprogram Listing of GetKey.PSL 





Variables 


None 


Discussion 


GetKey is useful when you have a limited number of nonconsecutive single keys 
you want to allow to be pressed in a program. Thus, GetKey is unlike GetReply, 
which is meant for replies from menus with consecutive keys from which to choose. 
Note that Reply is #27 for either the Esc key or any of the specialfunction keys, 
but Reply? is either #0 for the Esc key or other values for the special-function keys. 
You can use code like this to determine the keystroke when Reply is #27: 





GetKey(’’, Reply, Reply2), 
if Reply = #27 then 
tf Reply2 = 88 then 
uriteln(’ Ese key’) 
else 
uriteln(’ special-function key: ‘, ord(Reply2)) 
else 
writeln(’ not Esc or special-function key: ‘, Reply) 


Modifications 
None 
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KeyHit 





Name: KeyHit 
‘Type: boolean function 


Purpose: To detect whether a key bas been pressed and, if so, which 
one 


Calling Sequence: KeyHit(Reply, Reply2) 








Description 


KeyHit detects whether a key has been pressed. If a key has not been hit, the 
function returns a boolean value of false. If a key has been pressed, a boolean value 
of true is returned, and the parameters Reply and Reply2 contain the value of the 
key pressed. These parameters return values of type char and indicate the key with 
@ return code as shown in Appendix K of the Turbo manual. For “regular” keys, 
Reply has a value other than #27, and the value of Reply2 is irrelevant. For special- 
function keys (Fl through F10, Home, Del, etc. ), Reply is #27 (Escape), and Repl y2 
contains the value of the key. If the Esc key itself is pressed, Reply is #27, and 
Reply2 is #0. 


Input 
None 
Output 
KeyHit boolean ‘The function that indicates whether a key has been 
hit. A value of true means that a key has been 
Pressed. A value of false means that no key has been 
Pressed. 
Reply char The value of the key pressed. For special-function 
keys, Reply has the value #27. 
Reply2 char ~The second value for a specialfunction key (see 


Appendix K of the Turbo manual), or #0 otherwise 


Limitations and Error Conditions 


KeyHit reads possible keystrokes by using Turbo's logical input device, designated 
kbd, which does not buffer input. As a result, if more than one key is pressed before 
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the call to KeyHit, only the first keystroke is detected. The subsequent keystrokes 
are lost. 


‘The values of Reply and Reply2 are meaningless if KeyHit returns the value of false. 
Sample Usage 
program SampleUsageOfKeyHit; 


var 
Reply, Reply2 = char; 
Counter inte 





(SI KeyHit. PSL? 


BEGIN 
elrser; 
Counter := @, 
while not KeyHit(Reply, Reply2) do 
begin 
gotoxy (1, 3); 
Counter :* Counter + 1, 
writeln(’ Time counter =’, Counter); 
delay(58) 
end; 
writen; 
uriteln(’ Key’’s return code is’, ord(Reply):5, ord(Reply2) 5) 
END. 








‘This sample program continually updates an incremental counter in the upper left 
corner of the screen. When a key is pressed, the counter stops, and the value of 
the key is displayed. In the sample output that follows, the FI key is pressed when 
the counter reaches 98: 





Time counter = 98 





Key's return code is 27 59 
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Subprogram Listing of KeyHit-PSL 





Variables 


None 


Discussion 


‘This function is useful in interactive programs when you want to detect whether 
a key has been pressed, yet want execution to continue if no key has been pressed. 
KayHit does not wait for a key to be pressed; it merely detects whether one has 
been pressed. A typical use for KeyHit is in a “turtle” graphics sketching program, 
in which a line is continually drawn on the screen by the “turtle.” If certain keys 
are pressed, the turtle changes its direction, speed, or color. If no key is pressed, 
the turtle simply continues straight ahead. 

Remember that Reply is #27 if cither the Esc key or a special-function key is hit, 
but Reply2 is either #0 for the Esc key or other values for the special-function keys. 
‘The Discussion section of GetKey contains sample code to determine the actual 
keystroke when Reply is #27. 


This subprogram provides the solution to a problem that crops up during Turbo 
Pascal program development. When you want to have your program pause before 
it ends and returns contro! back to Turbo, an apparent solution is to use the code 
repeat until keypressed as your last program statement. The problem is that 
Turbo interprets the key you press as the first key pressed after Turbo regains 
control. The result, depending on which key you press, is that Turbo generally 
clears the screen and returns to its editor menu. A better solution is to use the 


GETTING KEYBOARD INPUT. 17 





KeyHit subprogram by saying repeat until KeyHit(Reply, Reply2). KeyHit re- 
‘moves from the buffer area the key that was pressed, thus preventing the key from 
being interpreted by Turbo when it regains control. 

Modifications 


None 


GetNumR 


Name: GetNumk 
Type: Procedure 


Purpose: To get a real number (or a special character) typed from 
the keyboard 
Calling Sequence: GetNusR(Nunber, CharFlag, Code) 











Description 


You are prompted to provide data entry from the keyboard, If you input a real 
number, GetNuaR returns its value. If you input a single (nonnumeric) character, 
that character is returned. If you press only the Enter key, that is detected. Other 
replies are flagged as illegal. The subprogram avoids Turbo's usual run-time error 
that occurs when you make an illegal entry for a numeric value in response to a 
readin statement. All input strings are terminated with the Enter key. 


Input 
None 

Output 
Number real ‘The real number entered from the keyboard 
CharFlag char +=» Nonnumeric character entered from the keyboard 
Code integer Flag indicating the type of keyboard input provided, 


namely 


Only Enter key was input, 





1: Single nonnumeric key was input; its value is 
in CharFlag. 
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0: Areal number was input; its value is in 
Number. 


1: Illegal entry, Code contains the position of 
the first character that cannot be interpreted 
as part of a real number. 


Limitations and Error Conditions 


Other than the standard alphanumeric keys, only the Shift key and the Enter key 
are intended for use with this subprogram. Data strings containing other specialized 
keys (such as Esc, tab, Ctrl, Alt, FI through FLO, cursor-movement keys, etc.) cause 
strange results. In most cases, Code is set to a nonzero value. These keys, however, 
do not cause a run-time error. Ctrl-C or Ctrl-Break interrupt the program, 


Any input string longer than 30 characters is truncated to 30 characters before the 
subprogram processes the string, 


GetNuaR uses Turbo's built-in val procedure to interpret your input strings as real 
numbers, The rules defining legal strings are generally the same as the rules for 
defining real constants, but there are some surprises. The only allowable characters 
are the plus sign (+), the minus sign (-), the decimal point (.), the exponential 
indicator (¢ or E), and the 10 digits (0-9). Any other character causes the string 
to be illegal as a real number. Blanks are illegal, even if they lead or trail the rest 
of the input string. The plus sign is legal only after the exponentiall indicator (and 
the + is optional there). The plus sign cannot lead the number. (The minus sign 
can lead a number, of course.) A comma cannot appear in the string, The decimal 
point is optional if the number has an integral value. Numbers expressed in ex- 
ponential form must be within Turbo's allowable range for real numbers (absolute 
value from 1.0E-38 to 1.0E+38). The exponential indicator must be followed by 
an (optional) plus or minus sign and at least one numeric digit. 


Some examples of legal expressions are -23.481, 364, 344, 14,, 14, , -, EO, and 
-O. The last four expressions evaluate to zero. Some illegal expressions are +23.0 
(leading + sign), 42642 (too big), 13.1 45 (contains a blank), and 29.E (nothing 
following the exponential indicator). When Code is sct to a nonzero value, the 
contents of Number are left unchanged. 
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Sample Usage 
Program SampleUsageOfGetNuar; 
var 
Number =: real; 
CharFlag © char; 
Code + Integer; 
($1 GetNumR. PSL) 
BEGIN 
repeat 
GetNumR(Number, CharFlag, Code); 
case Code of 
writeln(’ You hit only the CEnter] key’); 
“1: writeln(’ You hit the nonnumeric character: ‘, 
CharFlag); 
®: writeln(’ You entered the real number’’, Number) 
else 
writeln(’ You made an illegal entry’) 
end 
until 
(Code = -1) and (CharF li a) 
END. 


‘The following isa possible session produced with this program. The sample program 
terminates after you press Shift-Q. 





Entry? 23.14 

You entered the real nunber> 2 314@000000E+01 
Entry? -18e4 

You entered the real nunber= -1. B@q200000E+25 
Entry? 46.21 

You made an illegal entry 

Entry? 

You hit only the CEnter] key 

Entry? + 

You hit the nonnumeric character= + 

Entry? Q 

You hit the nonnumeric character: @ 
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Subprogram Listing of GetNumR.PSL 





Variables 
PromptString String constant displayed to prompt you for input 
Entry ‘Data string entered from the keyboard 
Discussion 


‘This subprogram is designed to facilitate numeric input when you may need special 
replies but want to avoid run-time errors for nonnumeric entries. For a simple 
example, suppose that you are writing a checkbook-balancing program. You need 
the user to provide the amounts of the checks written during the last month, one 
check at a time. The program prompts the user for cach amount (expressed as a 
real number in dollars and cents). But you also might allow some special replies 
to be made. One reply might be M, indicating that a mistake was made in the last 
value and the user wants to reenter it. Another reply might be F, indicating that 
the data entry is finished and all values have been entered. This type of keyboard 
input is perfect for GetNunR. 
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Modification 


PromptString is the message displayed to prompt the user for input, You may want 
to change PromptStr ing to a more suitable message for your particular application. 
If you make PromptStr ing the null string, no message is displayed. 


GetNumlI 
Name: GetNuml 
‘Type: Procedure 


Purpose: To get an integer number (or a special character) typed 
from the keyboard 
Calling Sequence: GetNuml (holeNumber, CharFlag, Code) 














Description 
‘You are prompted to provide data entry from the keyboard. If you input an integer 
number, GetNuml returns its value. If you input a single (nonnumeric) character, 
that character is returned. If you press only the Enter key, that is detected, Other 
replies are flagged as illegal. All input strings are terminated with the Enter key, 
‘The subprogram avoids Turbo's usual run-time error that occurs when you make 
an illegal entry for a numeric value in response to a readin statement, 





Input 
None 

Output 
UholeNumber real ‘The integer number entered from the keyboard 
CharFlag char. «= Nonnumeric character entered from the keyboard 
Code integer Flag indicating the type of keyboard input provided, 


namely 
-2: Only Enter key was input 
<1: Single nonnumeric key was input; its value is 
in CharFlag 


0: An integer number was input; its value 
Uno eNunber- 
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>1: Ilegal entry; Code contains the position of 
the first character that cannot be interpreted 
as part of an integer number. 


Limitations and Error Conditions 


Other than the standard alphanumeric keys, only the Shift key and the Enter key 
are intended for use with this subprogram. Data strings containing other specialized 
keys (such as Esc, tab, Ctrl, Alt, FI through F10, cursor-movement keys, etc.) cause 
strange results. In most cases, Code is set to a nonzero value. These keys, however, 
do not cause a run-time error. Ctrl-C and Ctrl-Break interrupt the program. 


Any input string longer than 30 characters is truncated to 30 characters before the 
subprogram processes the string. 


GetNum! uses Turbo's built-in val procedure to interpret your input strings as in- 
teger numbers. The rules defining legal strings are generally the same as the rules 
for creating integer constants, but there are some surprises. The only allowable 
characters are the minus sign (-) and the 10 digits (0-9). Any other character 
‘causes the string to be illegal as an integer number. Blanks are illegal, even if they 
lead or trail the rest of the input string. The plus sign is illegal; it cannot precede 
Positive integers. (‘The minus sign can lead a number, of course.) A comma cannot 
appear anywhere in the string, Also illegal are the decimal point and the exponential 
indicator, which are both legal in real numbers. Numbers must be within the range 
allowed in Turbo's integer precision (from -32768 to 32767). 


Some examples of legal expressions are -23, 4, -, and 000. The last two expressions 
evaluate to zero. Some illegal expressions are +23 (leading + sign), 33800 (too 
big), 13 45 (contains a blank), 29.0 (contains a decimal point), and -45E2 (contains 
the exponential indicator). 





Sample Usage 
Program Samp] eUsage0fGetNum!; 
var 
UholeNumber, Code © integer; 
CharFlag * char; 


CSI GetNum!, PSL) 
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‘BEGIN 
repeat 
GetNuml (WholeNumber, CharFlag, Code); 
case Code of 
=2: writeln(’ You hit only the CEnter] key’ ) 
* writeln(’ You hit the nonnumeric charac’ 





CharFlag); 
8: writeln(’ You entered the integer number* ‘, 
‘UholeNumber ) 


else 
writeln(’ You made an illegal entry’) 
end 
until 


"(Code = -1) and (CharFlag = “O") 


The following is a possible session produced with this program. Pressing Shift-Q 
ends the sample program. 






Entry? 567 
You entered the Integer nunber- 567 
Entry? -21 

You entered the integer nuaber: -21 
Entry? 32,000 

You made an illegal entry 

Entry? 

You hit only the CEnter] key 

Entry? + 

You hit the nonnumeric character: + 
Entry? Q 

You hit the nonnumeric character: 0 


Subprogram Listing of GetNumI.PSL 
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Variables 
PromptString String constant displayed to prompt you for input 
Entry Data string entered from the keyboard 
Discussion 


‘This subprogram is the companion to GetNun. You use GetNuml when integer 
numbers are needed for input, and GetNuaR when real numbers are required, See 
the Discussion section of GetNun® for additional details. 


Modification 
PromptStr ing is the message displayed to prompt the user for input. You may want 
to change PromptStr ing to a more suitable message for your particular application. 
If you make PromptString the null string, no message is displayed. 


WaitKey 





Name: WaitKey 
‘Type: Procedure 
Purpose: To make a program pause until a key és pressed 
Calling Sequence: lai tKey 
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Description 
UaitKey is a simple procedure that displays a message on the screen and waits for 
you to press a key to continue the program. Many programs require that this be 
done repeatedly, and using a procedure is preferable to using in-line code. 
Input 


None 


Output 


‘The message PRESS ANY KEY TO CONTINLE is displayed on the screen, the pro- 
cedure waits until you press any key, and then the procedure ends, thus causing 
the mainline program to continue. 


Limitations and Error Conditions 
Nearly any key on the keyboard will satisfy this subprogram and cause the program 
to continue, Some keys, however, will not work, including the Alt, Ctrl, Shift, Caps 
Lock, and Num Lock keys. 


Sample Usage 

Program SampleUsageOflia! tKey; 

($1 Wai tKey. PSL) 

BEGIN 
writeln(’ This message displayed first.’ ); 
al tkey; 


writeln(’ This one after a key 1s pressed.’) 
END, 


‘This test program produces the following output: 





This message displayed first. 


PRESS ANY KEY TO CONTINUE ** 
This one after a key is pressed 


26 TURBO PASCAL PROGRAM LIBRARY 





Subprogram Listing of WaitKey.PSL 





Variables 


None 


Discussion 


Wai tKey displays its message and repeatedly calls Turbo Pascal's keypressed func- 
tion until a key is pressed. For procedures that wait for a key to be pressed and 
enable you to examine which key it is, refer to the GetKey and GetReply 
subprograms. 


Modification 


‘You may want to delete the blank line displayed before the message by deleting 
the indicated statement. Our experience, however, is that the extra line is normally 
desirable for readability. 


Arr 





Name: KeyArr 
‘Type: Procedure 
Purpose: To enter numeric data from the keyboard into an array 
Calling Sequence: Keyfrr(Numérray, Count) 








Description 
‘This subprogram enables you to enter numeric data from the keyboard into a one- 


dimensional array. Keyfrr uses real data, but modifications for integer data are 


provided. The subprogram prevents the run-time error that normally occurs when 
nonnumeric data is entered for a numeric variable. 
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Input 
Numfrray real Array in which data is to be stored 
Count integer Number of elements currently in the array. (Normally 


this number should be zero before using KeyArr.) 


In addition, you must specify the following global const and type declarations in 
your main program. The number 100 is an example; your array size may vary. 





const 
ArraySize = 100, 


type 
frrayType = arrayC1.. ArraySize] of real; 
Output 
Numfrray real The same array, now containing data entered from 
the keyboard 
Count Number of elements now in the array 





Limitations and Error Conditions 


Unlike most programs, this subprogram docs not get a run-time error if you er- 
roneously enter nonnumeric data. Instead, the subprogram displays the message 
* Illegal. Please reenter. ** and asks for the same entry again. You enter 
the word END (all uppercase) to terminate data entry; otherwise, you fill the array 
full to ArraySize entries. A null entry is treated as nonnumeric data. If an entry is 
longer than 20 characters, only the first 20 are used. Count does not have to be 
zero before you use KeyArr. If, for example, you have 5 entries in you array and 
you want to enter more, set Count to 5. KeyArr willl put the next entry into element 
number 6. 











Sample Usage 
program SampleUsagefKeyArr; 


const 
ArraySize = 100, 


type 
ArrayType = array[t. ArraySize) of real; (Mod. *2) 
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var 
Nurfrray ~ ArrayType; 
Count, J = integer; 


(SI Keyfrr. PSL) 


BEGIN 

Count = 8 

KeyArr(NunArray, Count); 

uriteln(’Here 1s the data entered from the keyboard.” ); 

for J *= 1 to Count do writeln(NumWvrayJ0:12'4) (Mod. #2) 
END. 


‘When you enter and run this test program, it displays the following output: 





» Enter real data. Array size = 108 «# 
* Enter END to ond data entry. 

Entry number 1: 37.2 

Entry number 2: 15.61 

Entry number 3: 4.03 

Entry number 4° END 

** Data entry complete ** 

Hara 1s the data entered from the keyboard. 


Subprogram Listing of KeyArr.PSL 
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Variables 
EndFlag Text entered by user to indicate no more entries (’ END) 
Entry User's string entry, converted to numeric value for 
placement into array 
Code Condition code set by Turbo's val function, indicating 
whether Entry was successfully converted to a numeric 
value 
Discussion 


‘This subprogram is a handy way to enter numeric data into an array and is com- 
patible with several other array-handling subprograms (ShowArr, SortSIR, Sor tHR, 
LoadArr, and Saver). For two-dimensional arrays, see Key2Arr. KeyArr avoids the 
‘common problem encountered by Turbo programs in which keying illegal numeric 
data causes the program to blow up (that is, get a fatal run-time error). The solution 
is to use readin to enter the keyboard data into a string variable, which is then 
converted into a numeric value by Turbo’s val procedure. If the entry can't be 
converted correctly, it must have been nonnumeric, and KeyArr asks the user 10 
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reenter the data. See GetNua® to determine exactly what constitutes a legal numeric 
entry for val. 


Modifications 


1, To allow a null entry (that is, pressing the Enter key with no data) to 
signal the end of data entry, change ‘bad’ to ’ END’ in the line indicated 
by (Mod. 12. 


2. To enter data into an integer array instead of a real one, change the 
global type definition to indicate an integer array. You will also want to 
change the subprogram’s first ur iteln statement to Enter integer da 
instead of using Enter real data. To use the Sample Usage program, you 
also need to delete :4 from the last statement before the END. 
statement. 


Key2Arr 
Name: Key2Arr 
Type: Procedure 
Purpose: To enter keyboard data into a two-dimensional array 
Calling Sequence: Key2Arr(Num2Array, RowCount) 











Description 


You use this procedure to enter numeric data from the keyboard into a two-di- 
mensional real array. Our sample program uses an array that is 100 (rows) by 2 
(columns), but you can specify any size you need. The subprogram prevents the 
run-time error that normally occurs when nonnumeric data is entered for a numeric 
variable. 


Input 
NunZArray real Array in which data is to be stored 


RowCount integer Number of rows currently in the array. (Normally 
this number should be zero before you use KeyZArr.) 


In addition, you must specify the following global const and type declarations in 
your main program in order to indicate the exact number of columns and the 
maximum number of rows in the array. The numbers 2 and 100 are examples; your 
array size may vary. 
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const 
ColSize = 2; 
RouSize = 100; 


type 
Array2Type = arrayC1..RowSize, 1. ColSize] of real, 


Output 


Nun2Array real The same array, now containing data entered from 
the keyboard 
RowCount integer Number of rows now in the array 


Limitations and Error Conditions 


Unlike most programs, this subprogram does not get a run-time error if you er- 
roncously enter nonnumeric data. Instead, the subprogram beeps and displays the 
message ** I1legal. Please reenter. ** and asks for the same entry again. To 
terminate data entry, you enter the word END (all uppercase) when prompted for 
the first entry in a row; otherwise, you fill the array full to RowSize rows of entries, 
You must enter full rows of data. (In other words, you cannot enter END for the 
second column of a row, only for the first column.) A null entry is treated as 
nonnumeric data. If an entry is longer than 20 characters, only the first 20 are used. 
RowCount does not have to be zero before you use Key2Arr. If, for example, you 
have 5 rows of entries in your array and you want to enter more, set RowCount to 
5. Key2Arr will prompt you for entries beginning with the sixth row. 






Sample Usage 
program SampleUsage0fKey2Arr, 


const 
ColSize = 2; 
RowSize = 100; 


type 
Array2Type = arrayC1. RowSize, 1. ColSizel of real; 


var 
NumZArray > Array2Type; 
RowCount, J, K : integer; 
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($1 Key2Arr. PSLD 


BEGIN 
RowCount = 9; 
Key2Arr (Num2Array, RowCount); 
uriteln(’Here is the data entered from the keyboard.’ ); 
for J :* 1 to Rowount do 
begin 
for K = 1 to ColSize do 
ur ite(Num2ArrayCJ, KI:12 
writeln 
end 





END. 


When you enter and run this test program, it displays the following output: 
—— 


—Row nunber 1— 
Entry (1,11: 24.431 
Entry (1,23: 61.92 
—Row nunber 2— 
Entry (2,13: 19.6195 
Entry (2,21: 142.857 
—Row number 3— 
Entry (3,13: -13.003 
Entry (3,21: 1028.71 
—Row number 4— 
Entry [4,1]: END 
«3 rows entered. *# 
“* Data entry complete ## 
Here is the data entered from the keyboard. 
24.4318 61. 9200 
19.6195 142.6578 
~13,0038 1028. 7100 





Subprogram Listing of Key2Arr.PSL 
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Variables 
EndFlag Text entered by user to indicate no more entries (’ END‘ ) 
Entry User's string entry, converted to numeric value for 
placement into the array 
Code Condition code set by Turbo's val function, indicating 
whether Entry was successfully converted to a numeric 
value 
Discussion 


Just as KeyArr is used for entering data into a simple one-dimensional array, Key2Arr 
works with two-dimensional arrays. It is compatible with the family of subprograms 
handling two-dimensional arrays presented in this book (Shou2Arr, SortSI2R, 
Sor th2R, Load2Arr, and SaveZArr ) and can be used with the matrix-handling sub- 
programs (MatAdd, Hattult, Determ, etc. ). 
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Modification 


To cause the subprogram to display introductory messages before data entry begins, 
delete the line indicated by (Mod. #1) and the line five lines above it. This removal 
of the open and closed braces activates the four writeln statements treated as 
comments in the standard version of Key2Arr. 


KeyTxt 





Name: KeyTxt 
‘Type: Procedure 
Purpose: To enter text data from the keyboard into an array 
Calling Sequence: KeyTxt(TextArray, LineCount) 











Description 
KeyTxt is a procedure for entering text data from the keyboard into a string array. 
‘Once the data is in an array, you can save the data on disk with SaveTxt, reload 
the data into an array with LoadTxt, and manipulate the data with the text- 
manipulation subprograms, 


Input 
Textfrray string Array in which data is to be stored 
LineCount integer Number of lines of text currently in the array. 
(Normally this number should be zero before you 
use KeyTxt.) 
In addition, you must specify the following global const and type declarations in 
your main program. TextSize is the maximum number of lines of text allowed, 
and LineSize is the maximum length of each line. The numbers 100 and 80 are 
examples. 





const 
TextSize = 100; 


type 
LineSize = stringl6a3; 
TextArrayType = arrayli.. TextSize] of LineSize; 
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Output 


TextArray string ‘The same array, now with data entered from the 
keyboard 


LineCount integer Number of lines of text now in the array 


Limitations and Error Conditions 


If, during data entry, the number of lines you enter reaches TextSize, the sub- 
program automatically ends and returns control with the array full and LineCount 
equal to TextSize. If you enter text lines longer than LineSize, they are truncated 
(chopped off) after the first LineSize characters. No error message is issued. 
LineCount does not have to be zero before you use KeyTxt. For example, if you 
have 5 lines in your array and want to enter more, set LineCount to 5. KayTxt will 
put the next line into entry number 6 of the array and continue from that point 


Sample Usage 
program SamplaUsageOfKeyTxt, 


const, 
TextSize = 100; 


type 
LineSize = stringt8a3, 
TextArrayType = arrayCi. TextSize] of LineSize, 





var 
TentArray —~ TextArrayType; 
LineCount, J = integer, 





(SI KeyTxt. PSL) 


BEGIN 
LineCount == 9; 
KayTxt(TextArray, LineCount), 
uriteln(’ The text data entered is:"), 


for J := 1 to LineCount do writeln(TextArrayCJI) 
END 
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Here is the output of this test program with data entered by the user: 





** Enter text data. Array size = 100 lines ## 
*» Enter END to end data entry. =» 





** Data entry complete ** 

The text data entered is: 

Now is the time for all good people 
to cone to the aid of their 
sociopolitical entities. 


Subprogram Listing of KeyTxtPSL 
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Variables 

EndFlag The text entered by the user to indicate no more entries 
CEND’) 

ThisLine ‘The contents of each line as it is typed. ThisLine is moved 
into TextArray after verification that Thi sLine isn't equal 
to EndFlag. 

Discussion 


‘There are many ways to enter text data into an array so that a program can process 
the data. A method obvious to a Turbo programmer is to use the "Turbo editor” 
built into Turbo Pascal. You can use the editor to enter any text data the same 
way you enter a Pascal program. After you save the text data on disk, you can load 
the data into an array with the LoadTxt subprogram in this library and then operate 
on the data by using the other text-processing subprograms. 


You may require text data entry as part of a larger program, however. It is impractical 
to tell the person using the program to stop your program, create a file with the 
‘Turbo editor (or a word processor), and then go back to your program, Instead, 
you need to ask for the text input directly as part of your program. In such a case, 
KeyTxt can do the job. 


Modification 


Replace or delete the three writeln statements in the subprogram in order to alter 
the two prompting messages before and the one after the text data entry. You may 
‘want to replace these three statements so that you can customize the messages for 
your application, or you may want to delete the statements and provide similar 
messages in your main program instead. 





Creating Graphics Effects 





Effective graphics are a welcome enhancement to most programs, providing ani- 
‘mation, lucid presentation, friendliness, and just plain fun. Fortunately, Turbo Pascal 
provides easy access to the PC's graphics modes and capabilities. (We use the term 
grapbics a little loosely here. It refers not only to textual effects such as scrolling 
but also to higher-resolution pixel graphics. ) 


‘This chapter presents 10 subprograms in two categories: subprograms that require 
the Color/Graphics Adapter and those that work with either adapter (Monochrome 
or Color/Graphics). The subprograms are designed for maximum flexibility. All of 
them work with black-and-white monitors yet are easily modified to support color, 
windows, and Turbo's various text and graphics modes (as appropriate). None of 
the subprograms requires the use of anything other than standard Turbo Pascal. 
None uses the add-on machine-language routines for “extended graphics.” (Nor do 
the subprograms duplicate any of the capabilities included in these routines.) 


Three subprograms are strictly for use in one of Turbo’s text modes, These sub- 
programs work on PC systems with cither of the display adapters (Monochrome 
‘or Color/Graphics). In addition, cach of these subprograms is compatible with color 
and 40-column text modes for systems with the Color/Graphics Adapter. TextBox 
uses text characters to draw a rectangular box. This box can frame windows or 
highlight important text. Serol performs scrolling of text in any direction: left, 
right, up, or down. CursorOn toggles the cursor either on or off. 


‘The remaining seven subprograms require the Color/Graphics Adapter. Each of 
these subprograms is nominally configured for black-and-white graphics but can 
be easily modified for color graphics. In addition, each subprogram works in any 
of Turbo's graphics modes—medium or high resolution, GrCursor positions the 
cursor by using graphics coordinates on a graphics screen, thus facilitating the 
mixing of text and graphics on the same screen. GraphBox draws a rectangular box 
and can shade it in any of several styles. 

‘Two-dimensional graphs (X versus Y) are an impressive presentation tool for ap- 
propriate data. Drawing and labeling the axes can be a headache, however. This 
chapter includes five coordinated subprograms designed to relieve the pain, They 
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work together, sharing common parameters and thus simplifying the task of de- 
signing and labeling a graph. DoXAxis and DoYAxis draw a horizontal axis and a 
vertical axis, respectively, complete with two-tiered tick marks if desired. AnnXAxis 
and AnnYAxis annotate the axes, including the labeling of tick marks. Finally, 
AxisText stores a text array for use by the annotation subprograms. Chapter 18 
contains two full programs that use these subprograms to create a complete graph- 
ing capability. BarChart draws bar charts and histograms. XYGraph plots curves of 
“X versus Y." 


Many of the Sample Usage programs in this chapter are accompanied by figures. 
‘These figures were created on an EPSON® printer by using the PC’s Shift-PrtSc key 
combination to produce on paper an image of the screen. The GRAPHICS.COM 
program (included with PC DOS V2.0 and higher) was used. This program permits 
Shift-PrtSc to work with graphics on an IBM 80 CPS Graphics Printer and other 


compatible graphics printers. 





TextBox 


Name: TextBox 
Type: Procedure 


Purpose: To draw a “grapbics" box while the computer is in text 
mode 


Calling Sequence: TextBox(UpLeftx, UpLeftY, LoRightX, LoRightY) 








Description 
While the computer is in one of Turbo's text modes, TextBox draws a rectangular 
box. The location of the box is defined by the text coordinates of its upper left 
and lower right comers. The subprogram is fully compatible with any of Turbo's 
text modes, color settings, and windows. After drawing the box, TextBox repositions 
the cursor to where it was before the procedure call 


Input 


UpLeftX integer The X location of the upper left corner of the box in 
standard text coordinates 


UpLeftY integer The Y location of the upper left comer of the box in 
standard text coordinates 


LoRightX integer The X location of the lower right comer 
LoRightY integer The Y location of the lower right corner 


CREATING GRAPHICS EFFECTS 41 





All these coordinate locations are relative to any active window. That is, the upper 
left coordinates of the active window are always UpLeftX = 1 and UpLeftY = 1 


‘The computer should be in one of Turbo's text modes when the procedure is 
called. 


Output 


TextBox draws a rectangular box at the coordinate position defined by the input 
variables. 


Limitations and Error Conditions 


TextBox makes sure that the requested location of the box is within allowable 
limits. UpLef tX must be at least 1 but less than LoRi ghtX, UpLeftY must be at least 
1 but less than LoRightY. LoRightY cannot be more than 25. The procedure de- 
termines whether the computer is in 40- or 80-column text mode by interrogating 
hex memory location 44A. LoRi ghtX cannot be more than 40 or 80, depending on 
the current mode. If any of these restrictions is violated, the procedure is simply 
bypassed, and no box is drawn. 


No special checks are made for an active user-defined window. Incorrectly defined 
box locations (outside the active window) may cause box fragments on the screen, 
See the Discussion section, 


If the computer is in a graphics mode, no visible effect occurs. The memory-mapped 
area for text display is altered, however. 


Sample Usage 
program Samp eUsage0f TextBox; 


var 
UpLeftx, UpleftY, LoRightX, LoRightY: integer; 


($1 TextBox, PSL) 





BEGIN 
elrser; 
Upleftx == 15, 
UpLefty 5 
LoRightX == 31; 
LoRightY == 8, 


TextBox(UpLeftx, UpLefty, LoRightX, LoRightY); 
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window(UpLeftx + 1, UpLeftY + 1, LoRightX - 1, LoRightY - 1); 
gotoxy(t, 1); 
write’ TextBox frames windows nicely’ ); 
window(1, 1, 88, 25), 
gotoxy(1, 15) 
END. 


‘This sample program draws a box around a text window and then writes a message 
inside the window. Figure 3.1 shows the result. Note how the text wraps to a 
second line when the text reaches the edge of the text window. 


extHox frames || 





indows nicely | 


Fig. 3.1. A demonstration of TextBox 


Subprogram Listing of TextBox.PSL 
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CursorX 
CursorY 


Discussion 


‘The ASCI character for the upper left corner 

‘The ASCII character for the lower left comer 

‘The ASCH character for the lower right corer 

‘The ASCII character for the upper right corner 

‘The ASCII character for horizontal sides 

‘The ASCII character for vertical sides 

‘The current X location in text coordinates 

‘The current Y location in text coordinates 

Length of the box’s horizontal sides 

‘The X location of the cursor when the procedure is called 
The Y location of the cursor when the procedure is called 


TextBox uses text characters from the standard IBM PC character set. These char- 
acters are in the ASCII range above 127. You may redefine the characters. See the 
Modification section. 
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The coordinate system that defines the location of the box is the standard system 
used by Turbo. A location is specified by an X value and a Y value, X runs from 
1 at the left of the screen to 40 or 80 (depending on the text mode) at the right 
of the screen. Y runs from 1 at the top of the screen to 25 at the bottom of the 
screen. 


If you have defined a window, text coordinates are relative to your window. Be 
careful not to request that any part of the box be drawn outside the active window. 
If you do, undesirable box fragments are the likely result. 


A common use of TextBox is to draw a frame around a text window. The Sample 
Usage program illustrates this technique. If you have a window to be defined by 
window(XL, YL, XR, YR), then the appropriate frame can be drawn with 


TextBox(XL - 1, YL-1, XR+41, YR+1) 


Be sure that the call to TextBox precedes the call to window! 


TextBox is fully compatible with all of Turbo's text modes and features. Both 40- 
and 80-column modes are acceptable, in color or black and white. For color mode, 
the current foreground and background colors are used. TextBox works with both 
the Monochrome Adapter and the Color/Graphics Adapter as long as the computer 
is in text mode. 


Modification 


To draw the box, we chose characters that prod 
have a simpler one-line border by changing the AS 
lines indicated by (Mod. #1) to the following: 





a “double border.” You can 
1 character constants in the 








UpLeftChar = #216; 


LoLeftChar = #192; 
LoRightChar = #217, 
UpRightChar = #191; 
HorizChar = #196, 


VertChar = #179, 


Many other character choices are possible, of course. You can get a solid border, 
for example, by setting cach of these constants to #219. For other possibilities, 
consult a listing of the ASCII character codes. The IBM BASIC manual contains 
such a list in Appendix G. 
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Scroll 





Name: Scroll 
Type: Procedure 
Purpose: To scroll text in any of four directions 


Calling Sequence: Scroll (UpLeftx, UpLeftY, LoRightX, LoRi ghtY, 
Direction) 











Description 


‘This procedure scrolls text left, right, up, or down. You define a scrolling window, 
and only the text within that window scrolls. The scrolling text moves one character 
position in the indicated direction. Blanks are written into the trailing row or 
column, Scroll is compatible with any of Turbo's text modes, including 40- or 
80-column modes, color settings, and windows. 


Input 

UpleftX integer ‘The X location of the upper left corner of the 
scrolling window 

UpLeftY integer The Y location of the upper left comer of the 
scrolling window 

LoRightX integer ‘The X location of the lower right comer of the 
scrolling window 

LoRightY integer The Y location of the lower right comer of the 
scrolling window 


Direction integer Scrolling direction, namely 


0 Scroll left 
1 Scroll right 
2 Scroll up 


3° Scroll down 


UpLeftX, UpLef tY, LoRi ghtX, and LoRi ght define the scrolling window in standard 
text coordinates. These variables always reference the entire visible screen, even 
if you have an active text window created with Turbo's built-in window procedure. 
(Thus, regardless of any active text window, for the purposes of a scrolling window, 
the upper left comer of the screen is always UpLeftX = 1 and UpLeftY = 1. The 
lower right comer of the screen is always LoRightY = 25 and LoRightX = 40 or 
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80. The latter value depends on the active text mode.) If you set the scrolling 
window outside the active text window, you can scroll the entire active text win- 
dow. To scroll only inside your text window, set the scrolling window with the 
same parameters used in the call to window. 


Output 


All text within the scrolling window scrolls one character position in the indicated 
direction. The trailing row or column fills with blanks. 


Limitations and Error Conditions 


The procedure is bypassed with no effect if Direction is negative or greater than 
3. Be careful that you set the scrolling window correctly. No range checking occurs. 
If UpLef tx is greater than LoRightX or if UpLeftY is greater than LoRightY, the 
procedure is simply bypassed, and no great harm is done. If, however, one of the 
four coordinate positions is outside the screen boundaries (for example, LoRi ghtY 
is greater than 25), you may possibly hang the system, lose the cursor, or generate 
spurious screen images. 

Be especially careful with LoRi ghtX. If the computer is in one of Turbo's 40-column 
text modes, LoRi ghtX’s maximum meaningful value is 40. In one of Turbo's 80- 
column text modes, LoRi ghtX can have a value up to 80. 


Be careful also that you call Scroll only while the computer is in a text mode, 
Unpredictable screen alterations will result from a call while the computer is in 
4 graphics mode. 


You'll have a minor annoyance with screen “flicker” if all of the following are true: 
(1) you call Serol] while the computer is in one of the 80-column modes, (2) 
you request a relatively large scrolling window, and (3) your system is using the 
IBM Color/Graphics Adapter. This problem originates with the hardware video 
circuitry and takes considerable software manipulation to overcome. The problem 
does not occur with the Monochrome Adapter or with the Color/Graphics Adapter 
using one of the 40-column text modes 


Animated effects are sometimes dulled on IBM's monochrome monitor because the 
phosphors on that monitor vanish relatively slowly. Images, therefore, fade rather 
than crisply disappear. Try changing the delay time as explained in the Discussion 
section. 


Sample Usage 


The following program demonstrates scrolling in each of the four directions. The 
screen is filled with characters while the computer is in Turbo's 40-column, black- 
and-white text mode. Four separate scrolling windows are defined one at a time, 
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and text scrolls inside each window. A message at the bottom of the screen indicates 
the current scrolling direction just before scrolling occurs. 


program SampleUsageOfScroll; 


ve 





J, K, Me integer; 
($1 Scroll. PSL) 


BEGIN 
textmode(bu4d), 
for J == 1 to 15 do 
for K == 1 to 48 do 
urite(chr(k + J + 63)); 
writeln, 
for J == @ to 3 do 
begin 
Mes 10» J; 
case J of 
@ uriteln(’ Scrolling left’); 
1: uriteln(’ Scrolling right’ ); 
2: writeln(’ Scrolling up’ ); 
: writeln(’ Scrolling down’ ) 
end; 
delay (1000), 
for K ‘= 1 to 8 do 
begin 
delay(250); 
scroll( +2, 3, N+9, 12, J 
end 





end 
END, 


Subprogram Listing of Scroll.PSL 
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Variables 

Column Current text column: 

ColFactor ‘Component of Off due to the current column 

Row Current text row 

RowFactor Component of Off due to the current row 

Segm ‘Segment address of the screen area in memory, This 
address depends on the type of video adapter present 
(Monochrome or Color/Graphics). 

off Offset address of the screen area. This address is the 


number of bytes into the memory area where the current 
character is to be read or written. 


Screenllidth Width of the screen in units of text coordinates, This 
width is 40 or 80, depending on the current text mode, 


Screenidth2 Twice Screenllidth 


LastCol Column to be filled with blanks. This variable is in the 
embedded procedure Hor izental. 
LastRow Row to be filled with blanks. This variable is in the 


embedded procedure Vertical. 
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Delta ‘Term added to Off to get the correct memory offset. This 
variable occurs in the two embedded procedures. 


Discussion 


Scroll enables you to create many fancy effects in text mode. The means to scroll 
left and right are not often found in other program sources. One good example 
of this capability is the “moving ticker tape.” Here, new text enters from the right, 
and a general scrolling to the left creates easy reading. Sce the NewsWire program 
in Chapter 18 for a demonstration of this technique. 


Because Serol! only scrolls one row (or column), the procedure is usually used 
inside a loop. Repeated calls create a general scrolling effect. Experiment with 
placing a delay procedure between the calls to Scroll in order to find out what 
the most pleasing scrolling speed is for your application. Adjusting the argument 
in the delay call greatly changes the appearance of the scroll. Repeated calls to 
Serol! with the same input arguments continually scroll the text inside the given 
crolling window, 


‘The IBM PC uses memory-mapped displays. This means that the image of what's 
‘on the screen is kept in a section of memory. The video-refresh circuitry continually 
“looks” at this memory area to display what you see on the screen. Scroll works 
by directly changing this area of memory. As such, the procedure has autonomous 
control over the screen image regardless of the text mode, color setting, or text 
window set by other Turbo statements. Seroll looks at two special memory 
addresses in low memory. Hex 449 indicates the adapter (Monochrome or 
Color/Graphics) being used, which affects the segment address of the video 
memory-mapped area. Hex 44A indicates the current screen width (in characters). 
Scroll needs the screen width in order to determine correct address offsets for 
proper scrolling 


Scroll contains two embedded procedures: Horizontal and Vertical. They do 
the bulk of the needed work for horizontal scrolling and vertical scrolling, 
respectively, 

Modifications 


None 
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CursorOn 
Name: CursorOn 
‘Type: Procedure 


Purpose: To turn the cursor on or off while the computer is in text 
mode 


Calling Sequence: CursorOn(TurnOn) 








Description 


‘This handy procedure lets you control whether the cursor is visible, An invisible 
cursor is nice if you are doing special effects in text mode (such as scrolling or 
drawing character “graphics”). The reason is that a blinking cursor can be dis- 
tracting when a considerable amount of information on the screen needs to be 
absorbed. In this case, CursorOn enables you to remove the cursor. Of course, the 
procedure can restore the cursor as well. 





Input 
TurnOn boolean Indicator for the effect you want, namely 
true Turn on the cursor 
false Turn off the cursor 
‘The computer should be operating in (any) text mode when you invoke this 
procedure 


Output 
‘The cursor becomes invisible if TurnOn is set to false. The cursor becomes visible 
if TurnOn is set to true. 


Limitations and Error Conditions 
Results are unpredictable if the computer is in one of Turbo's graphics modes. 
Such modes support intermixed text and sometimes display the cursor. It is possible 
to lose the cursor completely if you use this subprogram while the computer is 
in a graphics mode. 





‘Turning the cursor on restores it to the default shape for your adapter card (Mono: 
chrome or Color/Graphics). If another routine changes the cursor's shape or size, 
CursorOn restores the cursor to the default shape. 
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Sample Usage 
This sample program displays explanatory messages while it turns the cursor off 
and then back on again. 


program SampleUsageOfCursorOn; 
($1 CursorOn, PSL) 


BEGIN 
elrser; 
uriteln(’Cursor will disappear in 5 seconds, but...*), 
delay (3000), 

CursorOn( 





uriteln, 
delay (3000), 
uriteln(’ It will reappear in 5 seconds.“ ); 
delay (5000), 
CursorOn(true) 
END. 





Subprogram Listing of CursorOn.PSL 
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Variables 
Reg A record of integer variables representing the 
microprocessor's registers and flags. Reg is used to pass 
values to Turbo's intr procedure. 
Discussion 


‘This procedure is compatible with any of Turbo's text modes using color or black 
and white, 


When the cursor is invisible, you can still display text as usual. The cursor is logically 
there, moving to the next character position as text is displayed. The cursor is 
exactly where you would expect it to be; it’s just not visible. When you use Cur sorOn 
to restore the cursor, it appears at the correct updated position, 


Access to cursor control is possible through the PC's ROM-resident BIOS (Basic 
Input/Output System). You use Turbo's intr procedure to invoke the ROM BIOS 
video service interrupt (hex 10). Service 1 sets the cursor to the size specified in 
the CX register. Because the default cursor size depends on the adapter card present, 
memory address hex 449 is read to indicate which adapter card (Monochrome or 
Color/Graphics) is in use. If the request is to tur the cursor on, the default cursor 
size is set. If the request is to turn the cursor off, bit 5 of the high-order byte of 
the CX register must be turned on. 


Modification 
Ifyou have IBM's Enhanced Color/Graphics adapter (EGA), change the line denoted 
by (Mod. #1) to the following: 


(os. san 


‘This sets the cursor to the correct default shape for this adapter. 
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GrCursor 








Name: GrCursor 
‘Type: Procedure 
Purpose: To position the cursor on a graphics screen 
Calling Sequence: GrCursor(xGraphic, YGraphic, XTextOffset, 


YTextOffset) 








Description 


Although text and graphics can be freely mixed in Turbo, moving the (invisible) 
cursor around a graphics screen is inconvenient. It would be nice to position text 
on a graphics screen with the same coordinate system used to position the graphics 
GrCursor provides this capability. 


Input 
XGraphic integer 


YGraphic integer 


XTextOffset integer 


YTextOffset integer 


Horizontal (X) position on a graphics screen in the 
current graphics units 


Vertical (Y) position on a graphics screen in the 
current graphics units 


Number of text-character positions to move the 
cursor in the X direction relative to the location 
defined by XGraphic and YGraphic. The number can 
be negative (a move to the left), zero (no move), or 
positive (a move to the right), 


Number of text-character positions to move the 
cursor in the ¥ direction relative to the location 
defined by Graphic and YGraphic. The number can 
be negative (an upward move), zero (no move), or 
positive (a downward move). 


‘The computer should be in one of Turbo’s graphics modes when you invoke this 


procedure. 


Output 


‘The invisible graphics cursor is moved to the Position on the screen defined by 
the graphics coordinates XGraphic and YGraphic. If XTextOffset or YTextOffset 
(or both) is nonzero, the cursor location is adjusted the appropriate number of 
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character positions. (Subsequent text displayed with a write statement is written 
at this cursor location.) 


Limitations and Error Conditions 


No range checking on the graphic coordinates occurs. If the requested location is 
outside the acceptable graphics domain, the cursor does not move at all 


‘The cursor positioning does not respect graphics windows but does accommodate 
regular text windows. If your application uses one type of window, you must also 
set the other type appropriately in order to achieve compatible results with this 
proceduré. 


Be sure that the computer is in one of the graphics modes before you call GrCur sor 





Sample Usage 

program Samp! eUsageOfGrCursor; 

var 
YGraphic, YGraphic, XTextOffset, YTextOffset « inte 
Leftx, Rightx Inte 


($1 GrCursor. PSL 





‘BEGIN 
Left% = 119; 
RightX == 450; 
YGraphic == 100; 
hire: 
hirescolor(white); 


drau(Leftx, YGraphic, RightX, YGraphic, white), 
XGraphic := (Leftx + RightX) div 2; 
XTextOffset °= -2; 
YTextOffset = 2; 
GrCursor(XGraphic, YGraphic, XTextOffset, YTextOffset), 
write’ Below’ ); 
GrCursor(LeftX, YGraphic, -1, 9); 
write’); 
GrCursor(RightX, YGraphic, 1, 8); 
urite(’R) 
END. 
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‘This sample program draws a straight line on a high-resolution graphics screen and 
then does some simple text labeling relative to the line. An L is placed at the left 
end of the line, an R at the right end, and the word Below under the line. Figure 
3.2 shows the result. 





Below 


Fig, 3.2.4 demonstration of GrCur sor. 


Subprogram Listing of GrCursor.PSL 





Variables 
XText ‘The X location of the cursor in text units 
YText ‘The Y location of the cursor in text units 
Discussion 


Actually, a cursor exists while the computer is in one of Turbo's graphics modes. 
‘You just can't see the cursor. It's as if a normal text screen were superimposed. 
‘over your active video screen. You can move the cursor around with gotoxy state- 
‘ments and also display text with write statements. In high-resolution graphics 
(hires), the text screen is 80 characters wide by 25 characters high. In medium. 
resolution graphics (grapheode or graphcolormode), the text screen is 40 char- 
acters wide by 25 characters high. 
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Each character position maps into an 8-by-8 square of graphics pixels on the video 
sereen. You can’t quite display a text character “anywhere” on the screen because 
the character must be confined to one of the 8-by-8 squares located at fixed po- 
sitions on the video screen. 


GrCursor positions the cursor at the text-character “square” that contains the pixel 
specified by XGraphic and YGraphic. Because each of these text character squares 
contains 64 pixels, any pair of values for XGraphic and YGraphic that specifies a 
point within the same square results in the sume cursor location, 


‘The procedure works equally well with high- or medium-resolution graphics. Just 
be sure that you use the graphics coordinates appropriate for the current graphics 
mode. 


Modifications 


None 


GraphBox 


Name: GrapbBox 
‘Type: Procedure 
Purpose: To draw boxes (with shading) while the computer is in 
any grapbics mode 


Calling Sequence: GraphBox(UpLeftX, UpLeftY, LoRightX, LoRightY, 
Color, ShadingType, Density) 











Description 


GraphBox draws a rectangular graphics box while the computer is in one of Turbo's 
graphics modes. This procedure is useful for framing, drawing bar charts, and many 
other graphics effects. You define the location and size of the box by specifying 
the graphics coordinates of the box’s upper left and lower right corners. You can 
draw any of several different types of shading inside the box. The subprogram is 
fully compatible with any of Turbo's graphics modes, color settings, and windows. 


Input 


UpleftX integer _X location of the upper left comer of the box in the 
standard coordinates of the currently active graphics 
mode 
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UpLeftY integer location of the upper left corner 
LoRightX integer _X location of the lower right comer 
LoRightY integer location of the lower right corner 


Color integer Graphing color. Its specification depends on the 
active graphics mode. In medium-resolution graphics 
(graphaode or graphcolormode), Color can be from 
0 to 3, indicating a color drawn from the active 
palette. In high-resolution graphics (hires), Color 
can be from 0 to 15. See the Turbo manual. 


ShadingType integer ‘The type of interior shading, namely 


Diagonal shading (up to right) 

Diagonal shading (down to right) 

Density integer The density of the interior shading in terms of the 
number of pixels between shading lines. Density has 
meaning when ShadingType is 2 through 5 

UpLeftX, UpLeftY, LoRightX, and LoRi ghtY are relative to any active graphics win- 

‘dow. Coordinate locations follow the Turbo standard of X increasing to the right 

and Y increasing downward. The upper left corner of the active window is always 

UpLeftx = 0 and UpLeftY = 


‘The computer should be in one of Turbo's graphics modes when you call GraphBox. 


© —_No shading (empty box) 
1 Filled box 

2 Horizontal shading 

3 Vertical shading 

4 

5 





Output 


GraphBox draws a rectangular graphics box at the specified location. The size, shad- 
ing, and color of the box are determined by the input variables, 


Limitations and Error Conditions 


GraphBox does some range checking on the box coordinates. UpLef tX must be at 
least 0 but no more than LoRightX. UpLeftY must be at least 0 but no more than 
LoRightY. The procedure is bypassed with no effect if one of these conditions is 
violated. If UpLeftX equals LoRi ghtX or if UpLeftY equals LoRightY, a line results 
instead of an enclosed box. No checks are made for any locations outside the active 
window (default or user-defined ). The box is clipped by the window boundary if 
you attempt to draw a line through this boundary. 
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Color works according to the active graphics mode. Modulo arithmetic corrects 
values outside the expected color range. Resulting colors are hardware dependent. 
See the Discussion section. 

If ShadingType is negative or greater than 5, an empty square results (as if 
ShadingType were 0). Density is irrelevant if ShadingType is 0 or 1. If Density is 
less than 1 when ShadingType is 2 through 5, an empty square results. If Density 
is 1 when ShadingType is 2 through 5, a filled square results (as if ShadingType 
were 1). 


No visible effect occurs if the computer is not in one of the graphics modes. 
Sample Usage 
program Samp] eUsage0fGraphBox; 
var 
UpLeftx, UpLefty, LoRightX, LoRightY = integer; 
Color, ShadingType, Density, J, DeltaX = integer; 


($1 GraphBox. PSL) 





BEGIN 
graphnode; 
DeltaX «= 52; 
Uplefty °= 39, 
LoRightY «= 15, 
Color = 3; 
Density ‘= 5; 
palette(1); 
for J i= @ to 5 do 
begin 
ShadingType °* J; 
UpLeftx = J» Deltax, 
LoRightX = UpLeftx + Deltax, 
UpLerty = LoRightY - 58 - J 10, 
GraphBox(UpLeftx, UpLeftY, LoRightX, LoRightY, 
Color, ShadingType, Density); 
end 
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Variables 
x Current X location in graphics coordinates 
° Current Y location in graphics coordinates 
Delta Difference between two graphics coordinates 
Discussion 


‘You can obtain many different effects by taking advantage of the shading options. 
Stacked-bar charts are one example. When two boxes of the same width are placed 
side by side, the two diagonal shadings will line up on the common vertical border. 
‘This creates a pleasing “herringbone” pattern. 
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Colors appear different on various display monitors. Usually color rendition is better 
on RGB monitors than on those using composite video. Even black-and-white mon- 
itors are affected in different ways by the color selections. Experiment with the 
color options (including background color) to determine the most pleasing effects 


for your needs. 
Modifications 
None 


DoXAxis 


Name: DoXAxis 
‘Type: Procedure 
Purpose: To draw a horizontal xaxis for a subsequent graph 


Calling Sequence: DoXAxis(xOrigin, YOrigin, XAxisL, NumSegsX, 
SubTicksX, Color) 











Description 
DoXAxis draws a horizontal x-axis while the computer is in any of Turbo's graphics 
modes. This procedure coordinates with other subprograms to facilitate the drawing 
of graphs and histograms. Input parameters control the location of the axis, its 
length, and the appearance of tick marks. DoXAxis is fully compatible with any of 
‘Turbo's graphics modes, color settings (if applicable), and windows. 


Input 
XOrigin inte 





X location of the axis origin (that is, the left 
boundary of the axis) in the standard coordinates of 





the active graphics mode 
YOrigin integer YY location of the axis origin 
xAxisL integer Length of the axis in standard units of the active 
‘graphics mode 


NunSegsX integer The number of equal segments in which to divide 
the axis. Each of these segments is delineated with a 
pair of primary tick marks (Including the first and 
last marks, the total number of tick marks is 
NunSegsX + 1.) If the axis has no tick marks, 
NumSegsX is zero. 
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SubTicksX integer The number of secondary tick marks to draw 
between each pair of primary tick marks 


Color integer Graphing color. Its specification depends on the 
active graphics mode. In medium-resolution graphics 
(sraphnode or graphcolormode), Color can be from 
0 to 3, indicating a color drawn from the active 
palette. In high-resolution graphics (hires), Color 
can be from 0 to 15 (or the predefined descriptive 
constants). See the Turbo manual 


XOrigin and YOrigin are relative to any active graphics window. The computer 
should be in one of Turbo's graphics modes when you call DoXAxts 


Output 


In the color specified, a horizontal line is drawn beginning at X = XOrigin and 
Y = YOrigin. The line extends XAxisL units in the positive X direction (toward 
the right), Primary and secondary tick marks are drawn if indicated by the input 
parameters, XOrigin, YOrigin, and XAxisL are in the units of the active graphics 
mode, 


Limitations and Error Conditions 


‘The procedure is bypassed with no effect if XAxisL is zero or negative. Only a 
straight horizontal line is drawn if NunSegsX is nonpositive. (In other words, no 
ick marks are drawn.) Primary (but no secondary) tick marks are drawn if 
SubTicksX is less than 1 


IfXAxisL is not an exact integral multiple of NumSegsX, the X locations of the primary. 
tick marks may not be exact integers. For graphics, however, exact integers are 
required. In such cases, the X locations of the tick marks are rounded to the nearest 
integer. Similarly, the X locations of secondary tick marks are rounded if necessary. 
Some nonuniform spacing of tick marks may result. 


Color works according to the active graphics mode. Modulo arithmetic corrects 
values outside the expected color range. Resulting colors are hardware dependent. 
See the Discussion section. 


If you try to extend the axis past the current window (either a user-defined window 
or the default window of the whole screen), the axis is “clipped,” but no fatal error 
results. 


No visible effect occurs if the computer is not in one of the graphics modes. 
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Sample Usage 
program SampleUsageOfDoxAxis; 


const 
Color = white; 


var 
Origin, YOrigin, XAxisL, NumSegsX, SubTicksx: int 





($1 DoXAxis. PSL 





graphbackground(black); 
hirescolor (white); 
uriteln(’ Sample X-Axes" ); 
XOrigin © 58; 
YOrigin ‘= 20, 
XAxish = 500; 
NunSegsX ‘= 10, 
SubTicksX ‘= @ 
DoXAxis(XOrigin, YOrigin, XAxisL, NusSegsX, SubTicksX, Color), 
DoXAxis(XOrigin, 6, XAxisl, NunSegsX, 3, Color); 
DoXAxis(XOrigin, 100, 368, 2, 8, Color); 
DoXAxis(XOrigin, 140, 368, 2, 11, Color), 
DoXAxis(XOrigin, 188, 380, @, 8, Color) 

END 


‘This sample program demonstrates a few of the possible y=axis that DoYAxis can 
produce. Figure 3.5 shows the result. 
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Fig. 34. A demonstration of Doxa 


Subprogram Listing of DoXAxis.PSL 
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Variables 
BigTickSize 


Smal lTickSize 


x 
JK 
Temp 


Discussion 


Don't overlook the value of the secondary tick marks for enhancing the readability 
of your eventual graph. As an example, for monthly data, you might use the primary 
tick marks to represent years and set SubTicksX equal to 11. This creates 12 sub- 


‘The length of the primary tick marks in units of the active 
graphics mode 

‘The length of the secondary tick marks in units of the 
active graphics mode 


Current X position in graphics units 
Loop indices 


‘Temporary real variable for the spacing between tick 
marks, This value is rounded if it's not an exact integer. 


divisions (corresponding to the months) within each year. 


If you use color, be aware that colors appear different on various monitors, You 
will probably have to experiment with the color options (including background 


color) to determine what best suits your needs. 


Modifications 


1. In the fine denoted by (Hod. #12, the constant BigTickSize controls the 
length of each primary tick mark You may change the default setting of 
10 to a larger or smaller (positive) integer. Larger values lengthen each 
tick mark, and smaller values shorten each one. 
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2. Similarly, the constant Saal ITickSize controls the length of each 
secondary tick mark. To control the length of each secondary tick mark, 
adjust the constant’s default setting of 5, 


DoYAxis 





Calling Sequence: 





Name: DoYAxis 
Type: Procedure 
Purpose: To draw a vertical y-axis for a subsequent graph 


DoYAxis(XOrigin, YOrigin, YAxisL, NumSegsY, 
SubTicksY, Color) 





Description 


DoYAx1s draws a vertical y-axis while the computer is in any of Turbo's graphics 
‘modes. This procedure coordinates with other subprograms to facilitate the drawing 
of graphs and histograms. Input parameters control the location of the axis, its 
length, and the appearance of tick marks. DoYAx!s is fully compatible with any of 
Turbo's graphics modes, color settings (if applicable), and windows. 


Input 
XOrigin 





YOrigin inte 
Yexisl 








NumSegsY integer 


SubTicksY integer 


X location of the axis origin (that is, the lower 
boundary of the axis) in the standard coordinates of 
the active graphics mode 


Y location of the axis origin 


Length of the axis in standard units of the active 
graphics mode 


‘The number of equal segments in which to divide 
the axis. Each of these segments is delineated with a 
pair of primary tick marks. (Including the first and 
last marks, the total number of tick marks is 
NunSegsY + 1.) If the axis has no tick marks, 
NunSegsY is zero. 


‘The number of secondary tick marks to draw 
between each pair of primary tick marks 
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Color integer Graphing color. Its specification depends on the 
active graphics mode. In medium-resolution graphics 
(graphnode or graphcolormode), Color can be from 
© to 3, indicating a color drawn from the active 
palette. In high-resolution graphics (hires), Color 
can be from 0 to 15 (or the predefined descriptive 
constants). See the Turbo manual 











XOrigin and YOrigin are relative to any active graphics window. The computer 
should be in one of Turbo’s graphics modes when you call DoYAxis 


Output 


In the color specified, a vertical line is drawn beginning at X = XOrigin and Y = 
YOrigin. The line extends YAxisL units in the Y direction toward the top of the 
screen. Primary and secondary tick marks are drawn if indicated by the input pa- 
rameters. XOr igin, YOr igin, and YAxisL are in the units of the active graphics mode, 


Limitations and Error Conditions 


‘The procedure is bypassed with no effect if YAxisL is zero or negative. Only a 
straight vertical line is drawn if NunSegs¥ is nonpositive. (In other words, no tick 
marks are drawn.) Primary (but no secondary) tick marks are drawn if SubTi cksY 
is less than 1. 


If YAx1sL is not an exact integral multiple of NumSegsY, the Y locations of the primary 
lick marks may not be exact integers. For graphics, however, exact integers are 
required. In these cases, the ¥ locations of the tick marks are rounded to the nearest 
integer, Similarly, the ¥ locations of secondary tick marks are rounded if necessary. 
Some nonuniform spacing of tick marks may result 


Color works according to the active graphics mode. Modulo arithmetic corrects 
values outside the expected color range. Resulting colors are hardware dependent. 
See the Discussion section of DoXAxis 


If you try to extend the axis past the current window (cither a user-defined window 
or the default window of the whole screen), the axis is “clipped,” but no fatal error 
results. 





No visible effect occurs if the computer is not in one of the graphics modes. 
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Sample Usage 
Program Samp] eUsageOfDoYAx is; 


const 
Color = white; 


var 
Origin, YOrigin, YAxisL, NumSegsY, SubTicksY: integer, 


($1 DoYAxis. PSL) 


BEGIN 
hires, 
graphbackground(black), 
hirescolor (white), 
writeln(’ Sample Y-Axes’ ); 
XOrigin <= 100, 
YOrigin == 188; 
YAwist. = 144; 
NunSagsY == 6, 
SubTicksY «= 9, 
DoYAxis(XOrigin, YOrigin, YAxisl, NusSegsY, SubTicksY, Color); 
DoYAxis(260, YOrigin, YAKisL, NunSegsY, 3, Color), 
DoYfx15(308, YOrigin, 9, 2, 8, Color), 
DoYAxis(408, YOrigin, %, 2, 7. Color), 
DoYfxis(508, YOrigin, 78, @ @, Color) 
END, 


This sample program demonstrates a few of the possible y-axis that DoYAx1s can 
produce. Figure 3.5 shows the result 
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Sample Y-Axes 





Fig. 3.5. A demonstration of DoVAs1s. 


Subprogram Listing of DoYAxis.PSL 
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Variables 
BigTickSize The length of the primary tick marks in units of the active 
graphics mode 
SmallTickSize ‘The length of the secondary tick marks in units of the 
active graphics mode 
Y ‘Current Y position in graphics units 
Jk Loop indices 
Tenp ‘Temporary real variable for the spacing between tick 
marks. This value is rounded if it’s not an exact integer. 
Discussion 
‘The comments in the Discussion section of the DoXAxis subprogram are applicable 
here, 


Depending on your screen, the usual problem of aspect ratios in PC video graphing 
arises with DoYAxis and DoXAxis. You may note that the length of primary tick 
marks (in pixels) is not the same in the two subprograms. (In other words, 
BigTickSize has a different value in cach subprogram. ) This difference is necessary 
to coordinate the physical length of tick marks drawn on the screen. IfBigTickSize 
has the same value in each subprogram, the x-axis primary tick marks are physically 
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longer than the y-axis primary tick marks. In the two subprograms, BigTickSize 
is set to look appropriate with high-resolution graphics (hires ) and typical screens, 
‘The same comments apply to the secondary tick marks and Smal 1TickSize. See 
the Modifications section. 


Modifications 
1, In the line denoted by (Hod. #12, the constant BigTickSize controls the 
length of each primary tick mark. You may change the default setting of 
22 to a larger or smaller (positive) integer. Larger values lengthen each 
tick mark, and smaller values shorten cach one. For medium-resolution 
graphics (graphmode or graphcolormode), try 


BigTickSize = 11; 


2. Similarly, the constant Seal 1TickSize controls the length of each 
secondary tick mark. To control the length of each secondary tick mark, 
adjust this variable’s default setting of 18. For medium-resolution 
graphics, try 


Sal ITickSize = §; 


AnnXAxis 


Name: AnnXAxis 





Type: Procedure 
Purpose: To annotate a horizontal x-axis for a subsequent graph 


Calling Sequence: fnnXAxis(XOrigin, YOrigin, XAxisL, NumSegsX, 
XTextfrr, Mid) 








Description 


‘This procedure provides the textual annotation for the x-axis of a graph. (The axis 
itself can be drawn with DoXAxis.) AnnXAxis labels tick marks and displays a title 
for the whole axis. The annotations can be centered below the tick marks or be- 
‘tween them. Input parameters work with DoXAxis to provide a consistent set of 
specifications for the x-axis. AnnXAxis is fully compatible with Turbo's high- or 
medium-resolution graphics modes. 
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Input 
XOrigin integer _X location of the axis origin (that is, the left 
boundary of the axis) in the standard coordinates of 
the active graphics mode 


YOrigin integer —_¥ location of the axis origin 


Axis integer Length of the axis in standard units of the active 
graphics mode 

NunSegsX integer Number of equal segments in which to divide the 
axis. Each of these segments is delineated with a pair 
of primary tick marks. (Including the first and last 
marks, the total number of tick marks is NuaSegsX + 
1.) If the axis has no tick marks, NunSegsX is zero, 


XTextArr string Array containing the string annotations to place on 
the axis. Element zero contains the label for the 
whole axis. The succeeding elements contain the 
labels for the primary tick marks. A null string in any 
element suppresses that annotation 


mid boolean Variable that indicates where the tick mark 
annotations should be located. If Hid is true, the 
annotations are centered in the spaces between the 
tick marks. If Mid is false, the annotations are 
centered below the tick marks. 


fanfcrayType must be declared in a global type declaration, preferably with ad- 


ditional global declarations. The following lines use the numbers 100 and 80 as 
‘examples; your values may be different. 





const 
MaxNumAxisAnn = 108, 


type 
AxisAnnSize = stringl80l, 
fnnfrrayType = array(®. MaxNumAxisAnn] of fAxisAnnSize; 


‘The parameters XOrigin, YOrigin, XAxi sL, and NunSegsX arc identical to their coun- 
terparts in DoXAxis. These parameters are meant to work compatibly between the 
‘two subprograms, and they have identical meanings in each subprogram. 


XOrigin and YOrigin are relative to any active graphics window. The computer 
should be in one of Turbo's graphics modes when you call AnnXAxis. 
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Output 
After DoXAxis displays the physical axis (with tick marks) on the screen, AnnXAxis 
provides the textual labeling for the axis. If Mid is false, a centered label is placed 
below each primary tick mark. If Mid is true, each label is centered in the space 
between tick marks. See the Discussion section. 
‘The axis title, if present, is centered with respect to the entire axis and placed 
below the other annotations, 
All annotations are located relative to XOrigin, YOrigin, and XAKisL. If these pa- 
rameters are identical in both DoXAxis and AnnXAxis, the physical axis and its 
labeling are compatible. 


Limitations and Error Conditions 
If NunSegsX is zero (or negative), no labeling of the tick marks is done, If XAxisL 
is zero, all annotations are superimposed just below XOrigin 
Although text can be freely mixed with graphics in Turbo, there are some restric- 


tions on the location of text relative to specific graphics lines. See the Discussion 
section 


‘This subprogram respects regular text windows but docs not accommodate graph- 
ing windows. If you use any windows, be sure to set window and graphuindow 
compatibly. If you try to extend an annotation outside the current text window, 
part of the annotation is displaced 


Annotations are drawn even if the computer is not in a graphics mode. Of course, 
AnnXAxis is meant to be used with DoXAxis, which requires a graphics mode. 


Sample Usage 
program SamplaUsageOfAnnXAxis; 





const 
MaxNumAxisAnn = 188; 


type 
AxisfnnSize = stringl86], 
AnnfrrayType = arrayl@..MaxNusAxisfnn] of Axi sAnnSize; 


var 
XOrigin, YOrigin, XAxisl, NumSegsX, J: integer, 
XTextArr AnnfirrayType; 
Mid boolean, 
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($I AnnXAxis. PSL) 
procedure DrawAxis(xOrigin, YOrigin, XAxisL, NumSegsX: integer); 


var 
x, Ji integer; 


begin 
draw(xOrigin, YOrigin, XOrigin + XAxisL, YOrigin, white), 
for J == 6 to NunSegsx do 
begin 
X := XOrigin + J * XAxisl div NusSegsx; 
draw(X, YOrigin, X, YOrigin + 18, white) 


end 
end, 
BEGIN 
hire: 
uriteln(* Sample Annotation on X-Axes” ); 
XOrigin «= 50, 
YOrigin == 46; 
XAKisL «= 480, 
NumSegsX i= 6; 
Mid = false; 


for J = 1to7 do 
str (108 * (J - 11, XTextArr£J2); 
XTextArr(@] <= "Production Capacity (Units per Day)’, 
DrawAxis(XOrigin, YOrigin, XAxisL, NumSegsX), 
AnnXAxis(XOrigin, YOrigin, XAxisL, NumSegsX, XTextArr, Mid); 
XTextArr(@] «= “Fiscal Year (First Quarter)’, 
XTextArr(1] <= * Mar’, 
XTextArr[2] == * Apr’, 
XTextArr([3] == ‘May’, 
DrawAxis(xOrigin, 148, 248, 3); 
AnnXAxis(xOrigin, 148, 240, 3, XTextArr, true) 
END. 





This sample program demonstrates a few of the possible axis annotations that 
AnnXAxis can produce. Figure 3.6 shows the result 
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Sawple Annotation on X-Axes 


t] 100 200 308 408 508 608 
Production Capacity (Units per Day) 


Mar Apr May 


Fiscal Year (First Quarter) 
Pig. 3.6. A demonstration of PenkAxts. 


Subprogram Listing of AnnXAxis.PSL 
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Variables 


TextLength ‘The length (number of characters) of one of the elements 
of the array XTextArr 


XText X location in text units for the cursor 
YText Y location in text units for the cursor 
J Looping index 
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NunToDo Number of annotations required for the tick mark labeling. 
‘This number depends on Mid. See the Discussion section. 

Spacing Number of graphics pixels separating each pair of primary 
tick marks 


RealXGraphic Temporary X location in graphics units 


Discussion 

AnnXAxis takes advantage of the fact that Turbo can mix text with graphics while 
the computer is in one of the graphics modes. Each text character occupies an 
B:by-8 pixel square on the graphics screen. Thus, in hires mode, the 80-by-25 
character grid can be thought of as superimposed over the 640-by-200 pixel graph- 
ics grid. A text character, however, cannot quite be “anywhere” on the graphics 
grid. Each character is confined to one of the 2,000 (80 times 25) character squares. 
‘Thus, if a tick mark is located near the edge of one of these 8-by-8 pixel text 
squares, the labeling appears slightly off center. This can be corrected by adjusting 
Origin, YOrigin, and/or XAxisL appropriately with the call to DoXAxts. (The idea 
is to have DoXAxis shift the axis location slightly so that the call to AnnXAxts can 
exactly center the annotations.) 


Depending on Mid, the number of clements required in the XTextfrr array varies. 
When Mid is false, there is one label for each primary tick mark. Since the number 
of primary tick marks is NunSegsX + 1, the number of elements in XTextArr should 
also be NunSegsX + 1. (Recall that element zero of XTextArr is reserved for the 
label for the whole axis.) When Mid is true, the labels appear between the tick 
marks. In this case, the number of annotations is only NunSegsX 


If you use crowded tick marks or if your annotations are lengthy, you may find that 
adjacent annotations overlap, This overlapping can be corrected by assigning null 
strings to the TextArr elements you want to blank out. For example, a null string 
assigned to every other clement causes only every other tick mark to be annotated. 
You can experiment with different configurations. 


Modifications 


1, The constant YOFfset1 controls how many text-character positions the 
tick mark annotations appear below the x-axis, (Recall that positive 
numbers are downward, and negative numbers are upward.) To move 
the labeling up or down, change this constant’s value in the line denoted 
by (Hod. #1) to any integer. 

2. The constant YO set2 controls how far the label for the whole x-axis 
appears below the axis. You may change this constant’s value in the fine 
denoted by (Mod. #2) to any integer 
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3. Tick mark annotations are nominally centered cither directly below the 
tick marks or in the spaces between them (depending on Mid). If you 
‘want to move the annotations left or right, change the value of the 
constant XOffseti to any integer. A positive value is a move to the right, 
and a negative value is a move to the left. This way, you can accomplish 
special positioning of the labels (such as left-adjusting them). 

4. XOffset2 moves the location of the label for the whole axis left or right, 
from its nominally centered value. You may change this constant to any 
integer. 


AnnYAxis 


Name: AnnYAxis 
Type: Procedure 
Purpose: To annotate a vertical y-axis for a subsequent graph 


Calling Sequence: AnnYAxis(Origin, YOrigin, YAxisL, NumSegsY, 
YlextArr, Mid) 











Description 

‘This procedure provides the textual annotation for the y-axis of a graph. (The axis 
itself can be drawn with DoYAxis.) AnnYAxis labels tick marks and displays a title 
for the whole axis. ‘The annotations are drawn horizontally and placed to the left 
of the tick marks. Annotations can be centered either even with the tick marks or 
in the spaces between the pairs of tick marks, Input parameters work with DoYAxis 
to provide a consistent set of specifications for the y-axis. AnnYAxis is fully com- 
patible with Turbo's high- or medium-resolution graphics modes. 





Input 
XOrigin integer _X location of the axis origin (that is, the bottom of 
the axis) in the standard coordinates of the active 
graphics mode 
YOrigin integer _ location of the axis origin 
Yaxisl integer Length of the axis in standard units of the active 
graphics mode 


NunSegsY integer Number of equal segments in which to divide the 
‘axis. Each of these segments is delineated with 
a pair of primary tick marks. (Including the first 
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and last marks, the total number of tick marks is 
NunSegsY + 1.) If the axis has no tick marks, 
NunSegsY is zero. 


YTextarr string Array containing the string annotations to place on 
the axis. Element zero contains the label for the 
whole axis. The succeeding elements contain the 
labels for the primary tick marks. A null string in any 
element suppresses that annotation, 

hid boolean Variable that indicates where the tick mark 
annotations should be located. If Mid is true, the 
annotations are centered in the spaces between the 
tick marks. If Mid is false, the annotations are 
centered even with the tick marks. 


AnnArrayType must be declared in a global type declaration, preferably with ad- 
ditional global declarations. In the following lines, numbers 100 and 80 are ex- 
amples; your values may be different, 





const 
MaxNumAxtsAnn = 100; 


type 
AxisfnnSize * stringl802, 
fnnArrayType = arrayC@..MaxNumAxisAnn] of AxisAnnSize; 


‘The parameters XOrigin, YOrigin, YAxisL, and NuaSegsY are identical to their coun- 
terparts in DoYAxis. These parameters are meant to work compatibly between the 
two subprograms, and they have identical meanings in cach subprogram. 


XOrigin and YOrigin are relative to any active graphics window. The computer 
should be in one of Turbo’s graphics modes when you call AnnYAxts 


Output 


After DoYAxis displays the physical axis (with tick marks) on the screen, AnnYAxis 
provides the textual labeling for the axis. If Mid is false, a centered label is placed 
vertically, even with each primary tick mark. If Mid is true, each label is centered 
in the space between the tick marks. (See the Discussion section. ) 


The axis title, if present, is centered with respect to the entire axis and displayed 
vertically from the top down. The title is placed to the left of the other annotations, 
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All annotations are located relative to Origin, YOrigin, and YAxisL. If these pa- 
rameters are identical in both DoYAxis and Ann¥Axis, the physical axis and its 
labeling are compatible. 


Limitations and Error Conditions 


If NunSegsY is zero (or negative), no labeling of the tick marks is done. If YAxisL 
is zero, all annotations are superimposed just to the left of YOrigin, 


Although text can be freely mixed with graphics in Turbo, there are some restric- 
tions on the location of text relative to specific graphics lines. Sce the Discussion 
section 


‘This subprogram respects regular text windows but does not accommodate graph- 
ing windows. If you use any windows, be sure to set both window and graphuindow 
‘compatibly. If you try to extend an annotation outside the current text window, 
part of the annotation is displaced. 


Annotations are drawn even if the computer is not in a graphics mode. Of course, 
Annvfxis is meant to be used with DoYAxis, which requires a graphics mode. 


Sample Usage 
Program Samp] aUsageDfAnnYAx!s; 


const 
MaxNumxtsAnn * 180; 


type 
AxisAnnSize = stringl8al; 
AnnfrrayType = arrayC@..MaxNumAxisAnn] of AxisAnnSize; 


var 
XOrigin, YOrigin, YAxisL, NumSegs¥, J : integer; 
YTextArr AnnrrayType; 
Mid boolean; 


{SI AnnYAris. PSL) 


procedure DrawAxis(xOrigin, YOrigin, YAxisL, NumSegsY: integer), 


var 
Y, Ji integer; 
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begin 
draw(xOrigin, YOrigin, ¥Origin, YOrigin - YAxisL, white 
for J '= @ to NunSegsY do 
begin 
Y © YOrigin - J YAxisl div NunSegsY; 
draw(XOrigin, Y, XOrigin - 22, Y, white) 





end 
end; 
BEGIN 
hire: 
writeln(’ Sample Annotation on Y-Axes’ ); 
Origin «= 159; 
YOrigin »= 187; 
YaxisL '= 168; 
NumSegsY «= 5; 
Mid false; 





for J i= 1 to 6 do 
str(25 © (J - 10:1, YTextAarr£J2); 
YTextfrr(@] «= ‘Units Shipped’ ; 
DrawAxis(XOrigin, YOrigin, YAKisL, NumSegsY); 
AnnYAxis(XOrigin, YOrigin, YAxisL, NuwSegsY, YTextArr, Mid); 
YTextArr(@] == ‘Year’; 
YTextArr(i] = “1960 
YTextArr£2] <= ‘1984 
YTextArr(3] <= * 1985" 
YTextArrl£4] == *1986" 
DrauAxis(45@, YOrigin, 128, 4), 
AnnYAnis(45@, YOrigin, 128, 4, YTextArr, true) 
END, 





‘This sample program demonstrates a few of the possible axes annotations that 
fnnYAxis can produce. Figure 3.7 shows the result. 
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Sanple Annotation on Y-Axes 
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Fig. 3.7, A demonstration of PeeivAats. 


Subprogram Listing of AnnYAxis.PSL 
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Variables 

TextLength The length (number of characters) of one of the elements 
of the array YTextArr 

XText X location in text units for the cursor 

YText Y location in text units for the cursor 

J Looping index 

NumToDo Number of annotations required for the tick mark labeling, 
‘This number depends on Mid. See the Discussion section, 

Spacing Number of graphics pixels separating cach pair of primary 
tick marks 


RealXGraphic Temporary X location in graphics units 
RealYGraphic ‘Temporary Y location in graphics units 


Discussion 


In the Discussion section of AnnXAxis, the comments pertaining to text and graphics 
mixing, the relationship between Mid and NumSegsX (or NunSegsY), and the use of 
null strings in XTextArr (or YTextArr) are relevant here. See that explanation, 


Possible crowding of an annotation is a more serious problem in AnnYAxis than 
in AnnxAxis. Crowding may occur because only 25 text characters are available 
vertically, but 80 text characters are available horizontally (in hires). Because the 
label for the whole y-axis is displayed vertically, a practical limit for its string length 
is 20 characters. The tick mark annotations are displayed horizontally; be sure that 
there is enough room for them between the y-axis and the left edge of the screen, 
See the Modifications section. 





Modifications 


1. The integer constant Off set1 controls how many text-character 
Positions each tick mark annotation appears to the left of the y-axis, 
Measurement is from the y-axis to the center of each annotation. To 
move the labeling left or right, you can change the value of XOffset in 
the line denoted by (Hod. #12. (Recall that increasing XOffseti moves 
the annotations toward the right, and decreasing XOFfset1 moves the 
annotations toward the left.) You may want to change this constant’s 
value if your labels are long. 
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2. The constant XOffset2 controls how far (in text characters) the label 
for the whole y-axis appears to the left of the y-axis. You may change 
this constant’s value in the line denoted by (Mod. #2) to any integer. 

3. A tick mark annotation is nominally centered either even with the tick 
marks or in the space between them (depending on Mid). If you want to 
move the annotations up or down, change the value of the constant 
YOFfsett to any integer. A positive value is 2 move downward, and a 
negative value is 2 move upward. Thus, you can accomplish special 
noncentered positioning of the labels. 

4, YOFfset2 moves the location of the label for the whole axis up or down 
from its nominally centered value. You may change this constant to any 








integer. 
AxisText 

Name: AxisText 

‘Type: Procedure 

Purpose: To fill a text array with strings suitable for numeric axes 
annotations 
Calling Sequence: AxisText(TextArr, NurSegs, Lowal, HighVal, 
RealFormat) 

Description 


Both the subprograms AnnXAxis and AnnYAxis require a string array (XTextArr 
and YTextArr, respectively) for storing the textual annotations for the axes tick 
‘marks. If these annotations are numeric, AxisText can automatically supply the 
strings needed for these arrays. For input, AxisText needs the numeric values at 
each end of the axis, the number of segments the axis is divided into, and the form 
(real or integer) for the annotations. The subprogram then stores in an array the 
appropriate strings for later use by AnnXAxis or AnnYAxis 


Input 
NunSegs integer The number of segments on the axis. AxisText 
generates NuaSegs + 1 strings. See the Discussion 
section. 
Lowval real The numeric value at one end of the axis. (Lowal 
corresponds to the left end of an x-axis or to the 
bottom of a y-axis.) 
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HighYal real The numeric value at the other end of the axis. 
(Hightal corresponds to the right end of an x-axis 
or to the top of a y-axis.) 
RealFormat boolean The type of string format produced. If RealFornat is 
true, real number strings are produced. If RealFormat 
is false, integer number strings are produced. 
NaxNumAxi sfnn and AnnfirrayType must be declared in global const and type dec- 
larations. Preferably, Axi sAnnSize is also declared globally as shown in the following 
lines, but this declaration is not required. The numbers 100 and 80 are examples; 
your values may be different 





const 
MaxNumAxisAnn = 108, 


type 
AxisAnnSize = stringl@l; 
AnnArrayType = array(®.MaxNunAxisfnn] of AxisAnnSize; 


Output 


Textfrr string Array of the resulting numeric values expressed as 
strings. The first element contains LouJal in string 
form. The NuSegs + 1 element contains Hi ghYal in 
string form. Intermediate elements, if any, contain 
‘equally spaced values between Lowal and HighVal 


Limitations and Error Conditions 


If NunSegs is less than 1 or greater than MaxNunéxisfnn, the procedure is bypassed 
with no effect. 

If RealFormat is false (indicating that integer number strings are desired), the 
absolute values of Lowal and HighVal must not be greater than 32767. If the 
absolute value of a number to be converted to an integer string is greater than 
32767, the value 0 (zero) is returned instead. 


Ifnecessary, numbers are rounded to fit the format specifications, See the Discussion 
and Modification sections for additional details regarding the limitations of real and 
integer formats. 
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Sample Usage 
program SampleUsageOfAxisText; 


const 
MaxNumfxi sAinn = 108; 


type 
AxisAnnSize = stringl88l; 
AnnArrayType * array(@, .MaxNumAxisfinn] of AxisAnnSize; 


var 





Textarr AnnArrayType; 
Lowel, HighYal = real, 
NunSegs, J integer; 
RealFormat boolean; 


(SI AxisText. PSL) 


BEGIN 
NumSegs 
Lowa 
Hi ghVal = 2.00, 
RealFormat <= true; 





AxisText(TextArr, NumSegs, Lowal, HighVal, RealFormat); 


writeln(’ Axis annotations in real format’); 
for J ‘= 1 to NumSegs + 1 do 
writeln(Textérr(J1), 
writeln, 
AxisText(TextArr, 4, 0, 100, false), 
uriteln(’ Axis annotations in integer format’ ), 
for J == 1 to 5 do 
writeln(TextArr£J) 
END, 
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Running this test program produces the following output: 





Axis annotations in real format 
71.08 
8.58 


press 
Sess 


Axis annotations In integer format 


Subprogram Listing of AxisText.PSL 
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Variables 
Interval (HighYal - Lowa!) divided by NunSegs 
RealVal A real number value to be converted into a string and 
later stored in TextArr 
Intval RealVal converted to an integer 
J Looping index 
Discussion 


For most graphs and bar charts, at least one axis is numeric. This subprogram 
provides a convenient way to store the string annotations for such axes for later 
Use by AnnXAxis or AnnYAxis. The parameters in AxisText are designed for com- 
patibility with AnnXAxis and AnnYAxis. Table 3.1 shows how the critical variables 
correspond in these three subprograms, 





Table 3.1 
Corresponding Variables in the Axes Subprograms 


procedure fx sText procedure Panitfnis procedure AnnYAxis 
TextArr XTextfrr YTextArr 


NumSegs NumSegsX ‘NumSegsY 





(For the following paragraph, some knowledge of how AnnxAxis and AnnYAxis work 
is assumed. See those subprograms for details. ) 


AxisText produces NusSegs + 1 elements in the TextArr because that is what 
fnnXAxis and AnnYAxis expect when the tick marks are annotated. (There are 
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NunSegs + 1 tick marks.) If, however, the eventual annotations are to be located 
between the tick marks, the umber of annotations required is only NunSegs. In 
this case, you can “trick” AxisText into producing the correct number of anno- 
tations by setting NurSegs one less than NunSegsX (or NunSegsY), 

LouVal can be less than HighVal, If so, the resulting annotations are in descending 
sequence, 

In integer mode, the strings are whatever length is required to express the resulting 
number. Truncation may be necessary in real mode, however. See the Modification 
section. 


Modification 


For real numbers, the format can be whatever you want, Our default setting is fixed 
format with two digits to the right of the decimal point. You may change this setting, 
to any real-number format right after RealVal in the line denoted by (Mod. #1), 





Creating Screen Displays 


‘The previous chapter deals with creating graphics effects. This chapter presents 
subprograms that assist you with displaying standard text on the screen. 

Tab and TabXY are cursor-movement functions you can use in a write or uriteln 
statement, Tab moves the cursor to a specified location on the current line, and 
TabXY moves the cursor anywhere on the screen. These functions case the some: 
times difficult task of aligning screen output in neat columns. For high-speed screen 
‘output, you can try ShouFast, which displays screen output about 10 times faster 
than Turbo’s write or uriteln. Finally, Shoufrr and Show2Arr display the contents 
of one- and two-dimensional arrays, respectively. 


Tab 





Name: Tab 
Type: char function 
Purpose: To move the cursor to a specified column 
Calling Sequence: Tab(TabCol) 








Description 


Tab moves the cursor to a specified column in the current line, Because Turbo 
doesn't provide such a feature, you can use this function in a write or writeln 
statement. Turbo’s gotoxy procedure enables you to move the cursor anywhere 
you want, but gotoxy cannot be used in write or uriteln. If you need to display 
columnar output on the screen, especially output containing variable-length text 
strings, then Tab is an easy way to move the cursor to the required columns. 
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Input 
TabCol integer The column number (1-79) where the cursor is to 
be moved 
Output 
Tab char ‘The function Tab returns a char value of ASCU 8 


(backspace). The backspace aids in moving the 
cursor to the specified column when you use Tab in 
awrite or writeln statement. See the Discussion 
section. 


Limitations and Error Conditions 


TabCol must be in the range from 1 to 79. The number is assumed to be 1 if it 
is less than 1, oF 79 if it is greater than 79. The current cursor position docs not 
matter, nor does it matter whether any text is already on the current screen line, 
‘This subprogram works for screen output only. If you use Tab with a urite or 
uriteln statement directed to the printer or a disk file, a single character with the 
value ASCII 8 (backspace) is sent to the printer or disk file, and the cursor is moved 
to position TabCol + 1 of the current screen line. 





Sample Usage 
program Samp|eUsage0fTab; 


var 
TabCol: integ 





($I Tab. PSL) 


BEGIN 
TabCol ‘= 15; 
wr iteln(’ 12345678901234567898 - “Ruler” line’ ); 
uriteln(’ First line’, Tab(TabCol), ‘x’ ); 
uriteln(’ Second line’, Tab(TabGol), *Y" ); 
writeln(’ abedefghtj’, Tab(é), “Z°) 

END. 


In the following program output, the first line is a “ruler” line, indicating column 
numbers in the other lines. The next two lines show how Tab moves the cursor 
to a fixed column (15) after displaying variable-length string data. The last line 
demonstrates how the cursor can be moved over data already on the same line. 
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12845678901234567898 - “Ruler” line 
First line X 

Second line Y 

abedeZghi j 


Subprogram Listing of Tab.PSL 





Variables 


None 


Discussion 


Displaying data in nice even columns can sometimes be quite awkward. Suppose 
that you are displaying one or more small fields in many different lines on the 
screen. For all the lines, you want to display something starting in, say, column 72. 
Without the Tab function, you can accomplish this task in several unwieldy ways. 
For instance, you can display your first few fields and then display the appropriate 
number of blank spaces until you reach column 72. Or you can end your write 
statement after the first ficlds, use the gotoxy procedure to move the cursor to 
‘column 72, and then use another write. A much simpler way, however, is to use 
the Tab function. The code will look something like this: 


writeln(A, B, Tab(72), 0); 


Because Turbo does not allow the use of a procedure from within the built-in write 
(or uriteln) procedure, we got a little tricky in creating Tab. Turbo docs allow 
a function within write. We therefore used a char function that displays a cursor- 
‘movement character rather than a visible character or number. We moved the 
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cursor out one position beyond the TabCo! position and then set the Tab function 
value to the backspace character so that write moves the cursor backward to the 
position you specify. Because of this approach, the maximum allowable value for 
TabCol is 79, not 80. 


Another function that would be handy in Turbo is Space. Suppose that you are 
displaying two variables and you want to leave N spaces between them. If a space 
function existed, you could use the code 


writeln(f, Space(N), B); 


We would have included such a function in this book, but you can just as easily 
get the same effect from standard Turbo commands by writing a null string (two 
consecutive apostrophes) followed by a length variable, as in 


writeln(a, “*:N, B); 


‘This technique has the advantage of working equally well for printer, disk, or screen 
output. 


Modifications 
None 


TabxY 





Name: TabXY 
Type: char function 
Purpose: To move the cursor to a specified column and row 
Calling Sequence: TabXY(TabCol, TabRow) 











Description 
TabXY moves the cursor on the screen to both the column and the row you specify. 
Like Tab, TabXY can be used in a ur ite or writeln statement because Turbo doesn't 
Provide such a feature. Turbo's gotoxy procedure enables you to move the cursor 
anywhere you want, but gotoxy cannot be used in write or writen. You will often 
find it simpler to use TabXY to position the cursor on the screen than to use nu- 
merous paired write and gotoxy statements. 
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Input 
TabCol integer The column number (1-79) where the cursor is to 
be moved 
TabRow integer The row number (1-25) where the cursor is to be 
moved 
Output 
TabxY char The function TabXY returns a char value of ASCII 8 


(backspace). The backspace aids in moving the 
cursor to the specified column when TabXY is used 
in a write or writeln statement. See the Discussion 
section. 


Limitations and Error Conditions 


TabCol must be in the range from 1 to 79. The number is assumed to be 1 if it 
is less than 1, or 79 if it is greater than 79. Similarly, TabRow must be in the range 
from 1 to 25. The number is assumed to be 1 if it is less than 1, or 25 if it is 
greater than 25. The current cursor position makes no difference, nor does it matter 
whether any text is already on the screen. This subprogram works for screen output 
only. If TabXY is used with a urite or writeln statement directed to the printer 
or a disk file, a single character with the value ASCII 8 (backspace) is sent to the 
printer or disk file, and the cursor is moved to column TabCol + 1 and row TabRow 
on the screen 


Sample Usage 


program SampleUsage(f TabxY; 





($1 TabXY PSL) 


BEGIN 
clrser; 
wr iteln(’ 123456789012345678%0 ), 
writeln(TabXY(4, 2), °2', TabXv(1,3), “3, Tabxv(1,4), “4°); 
uriteln(Tabxy(5, 4), “x, Tabxv(2,3), “¥, TabXY(12,2), 2°); 
wr iteln(TabXY(1, 5), ‘Done’ ) 

END. 
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In the following program output, the first line is a “ruler” line, indicating column 
‘numbers in the other lines. The second writeln statement of the sample 

displays the row numbers for rows 2 through 4. The third wr iteln statement dis- 
plays X, Y, and Z. at various sercen locations, using TabX¥ to move the cursor, The 
last writeln moves the cursor below the area previously used and displays Done. 


127345678901234567890 
2 z 

oY 

4x 

Done 


Subprogram Listing of TabXY.PSL 





Variables 
None 


Discussion 


‘The Discussion section for Tab explains its benefits and the reasons why it is written 
ina slightly tricky way. Those comments are applicable here also, except that TabXY 
adds the capability of row movement. As with Tab, the coding method for TabCol 
limits the maximum allowable value to 79, not 80. 
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Modifications 


None 


ShowFast 


Name: ShowFast 





Type: Procedure 
Purpose: To display a string of text on the screen at bigh speed 
Calling Sequence: ShouFast(Message, Column, Row) 











Description 


‘The ShouFast subprogram displays on the screen a string of text in roughly 1/10 
the time required by wr ite or wr iteln. Although ur ite and wr iteln are fast enough 
for most purposes, a faster display is sometimes needed. If you use write or wr iteln 
to fill the screen with text, the time required is about 2.0 seconds with the Mono- 
chrome Adapter or about 2.5 seconds with the Color/Graphics Adapter. If you use 
ShouFast, filling the screen takes about 0.2 seconds in either case, 


Input 
Message string The string of text you want to display on the screen 
Column integer The column number (1-80) where you want the 
displaying to begin 
Row integer The row number (1-25) where you want the 





displaying to begin 


In addition, you must specify in the main program the following global type 
declaration: 


ty 
String255 = stringl2553; 


Output 


‘The output of this subprogram is text displayed on the screen, beginning in the 
column and row you specify and continuing for the length of Message 
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Limitations and Error Conditions 


Message can be any legal string, from 0 (zero) to 255 characters long. Column and 
Row must be within the ranges shown previously (1-80 and 1-25, respectively), 
but no range checking is done by the subprogram. Nor is checking done to de- 
termine whether the message extends beyond the end of the screen. (ShouFast 
does not scroll the screen if the message extends beyond column 80 of row 25; 
the subprogram continues putting the text into memory areas beyond the end of 
the screen.) You must be certain to check that the starting location and length of 
the message string are valid. If you don't, the results may be unpredictable, The 
cursor position is not changed by ShowFast. You must move the cursor yourself 
(with gotoxy) if you plan to use write or writeln to put more output on the same 
screen used by ShouFast. This subprogram was tested on a standard IBM Personal 
‘Computer using both the Monochrome Adapter and the Color/Graphics Adapter 
in 80-column text mode. The subprogram should work on other compatible com- 
puters that use the same screen memory locations, but verification is up to you. 


Sample Usage 
program SamplollsageOfShouFast, 





type 
String255 = stringl2553, 
var 
Message © String255, 
J integer, 


(SI ShowFast. PSL) 


BEGIN 
clrser; 
delay (2000); 
Message := ‘These lines were displayed by Turbo'’s “writeln” ; 
for J = 1 to 24 do 
uriteln(Message), 
delay (5008), 
elrsor, 
delay (2000), 
Message © ‘These lines were displayed by TPPL’’s “ShouFast"”; 
for J '= 1 to 24 do 
ShowFast (Message, 1, J); 
delay (5000), 
gotoxy(1, 24) 
END 
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This sample program fills the screen with messages in two different ways. You can 
compare the times required for each method. First, the program clears the screen, 
pauses for 2 seconds, and displays this message on lines 1 through 24, using wri teln: 


These lines ware displayed by Turbo’ s “writeln® 


‘Then the program pauses for 5 seconds, clears the screen, pauses for 2 more see- 
‘onds, and displays this message on lines 1 through 24, using ShouFast: 


These lines ere di splayed by TPPL’ s "ShouFast” 


Subprogram Listing of ShowFast.PSL 





Variables 
Vidloc integer The segment address of the start of video memory. 
For the Monochrome Adapter, the address is hex 
B000. For the Color/Graphics Adapter, the address is 
hex B800_ 
Offset integer The number of bytes into the screen memory area 


where the current character is to be placed. For the 
first 5 screen locations, Offset is 0, 2, 4, 6, and 8. 
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Pointer byte —_A pointer to the current character in the Hessage 
string being placed on the screen 

Discussion 
‘An IBM PC uses memory-mapped displays. This means that the text you see on the 
screen is a copy of the text encoded in a certain area of the computer's memory. 
ShouFast gains its speed by putting directly into the appropriate memory locations 
the text to be displayed instead of taking the longer (and slower) path used by 
ur ite and writeln, Beware of the dangers of this fast approach! If other computers 
(from IBM or other manufacturers) change the memory areas they use, or change 
the indicator at location hex 449 (indicating that the Monochrome Adapte: in 
use if the contents are equal to 7, or the Color/Graphics Adapter otherwise), then 
this subprogram will no longer work correctly. By the same token, ShouFast is 
based on the scheme of 2 bytes (a data byte followed by an attribute byte) rep- 
resenting each screen position. ShouFast puts the data bytes into every other mem: 
ory location, skipping over the attribute bytes. If this scheme is altered, the 
subprogram will fail, But given these caveats, ShowFast can be useful in many in- 
stances when a faster display is necessary. For example, you can use ShouFast to 
avoid sluggish response when you're paging through screens full of data. 





Modifications 


None 


ShowArr 


Name: ShowArr 
Type: Procedure 
Purpose: To display a numeric array’s contents on the screen 
Calling Sequence: Shoufirr (Nunfrray, Count) 














Description 


This procedure displays on the screen the elements of a real array. If there are 
more elements in the array than there are lines on the screen, ShouArr waits for 
you to press a key to continue after displaying each full screen, 
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Input 
Num@rray real Array in which data is stored 
Count, integer Number of elements to be displayed 


In addition, you must specify in your main program the following global type dec- 
laration, preferably using the global const declaration shown. The number 50 is 
an example; the size of your array may differ. 





const 
ArraySize = 50, 


type 
ArrayType = arrayCl. ArraySize] of real 


Output 
No changes are made to the array’s contents or Count. The contents of the array 


are displayed on the screen in the format shown in the Sample Usage section that 
follows 


Limitations and Error Conditions 


Count must be greater than zero; otherwise, the subprogram exits without displaying, 
anything, 


Sample Usage 
program SampleUsageOfShourirr, 


const 
ArraySize = 50; 


type 
ArrayType 





rrayC1.frraySize] of real; (Hod, #4) 
var 

NumArray = ArrayType; 

Count + integer; 


($1 ShowArr. PSL) 
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3 
Showfirr(Nunfrray, Count) 
END. 


Following is the output of this test program: 





= Press a key to continue ** 


Subprogram Listing of ShowArr.PSL 
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Variables 


Rows 
Gap 


J 


Discussion 


Number of rows (lines) that may be displayed on one 
sereen 

Two blank spaces, used in separating the display of the 
element number from the contents of the array element 


Subscript that varies from 1 to Count, indicating the 
current element being displayed 


‘The logic of a subprogram to display all the elements in an array should be so 
straightforward that the subprogram would be almost trivial. A single executable 
statement like the following should be just about enough: 


for J «= 1 to Count do wri teln(NumArrayCJI); 


Indeed, in many circumstances this és enough. Often, though, just a little more is 
needed. ShouArr takes two extra steps: (1) displays the element number to the 
left of each element's contents, and (2) pauses after each 20 elements (and at the 
end of the list) so that you can see the output before it scrolls off the screen. The 
subprogram remains quite simple, yet you may be surprised to see how complicated 
some programmers make such a thing. 


Modifications 


1. To change the number of rows (lines) displayed on each screen before 
waiting for a key to be pressed, change 28 in the statement indicated by 
(Mod, #1) to any integer from 1 to 23. 


2. To change the spacing between the element number and its contents on 


cach line, change the number of spaces between apostrophes 


in the 





statement indicated. 


3. Change the format of each element's contents from exponential (floating 
point) notation to fixed-decimal notation by changing the indicated 
statement to something like this: 


writeln(J:4, Gap, NumArrayCJ]:16:8); 


See the Turbo manual for details about formatting real numbers. 
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4, To use this subprogram to display the contents of integer arrays rather 
than real ones, change the global type declaration to 


type 
ArrayType = arrayCi..ArraySize] of integer; 


Show2Arr 
Name: Show2Arr 
Type: Procedure 


Purpose: To display a two-dimensional array’s contents on the 
screen 


Calling Sequence: Shou2Arr(Num2Array, RowCount, N, M, Columns) 














Description 
‘This procedure displays on the screen the elements of a two-dimensional real array. 
If there are more elements in the array than there are lines on the screen, Show2Arr 
pauses after the screen fills and waits until you press a key before continuing, 


Input 
Num2Array real Array in which data is stored 
RowCount integer Number of rows of elements to be displayed 


N Integer Width of the field for displaying each clement with 
‘Turbo’s write procedure. If the width is 0 (zero), 
floating-point format is used. 


4 integer Number of digits to be displayed to the right of the 
decimal point for cach element 


Columns integer Number of columns of output to be displayed on the 
screen 


In addition, you must specify in the main program the following global const and 
type declarations in order to define the array. RowSize, which is the maximum 
number of rows the array can contain, is not required. But for compatibility with 
other subprograms, RowSize is recommended as the way to define Array2Type. The 
numbers 2 and 100 are examples; the size of your array may 
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const 
ColSize = 2; 
RouSize = 100; 


type 
Array2Type = arrayCi. RowSize, 1, ColSize] of real; 


Output 


No changes are made to the array’s contents or to the other variables passed to 
the subprogram. The contents of the array are displayed on the screen in one of 
the formats shown in the Sample Usage section, depending on whether N is zero 
or the width of a write field, 


Limitations and Error Conditions 


RowCount and Columns must be greater than zero, and N and M must be 
nonnegative. Otherwise, the subprogram beeps, then displays the error message 
#*Paramater error inShou2Arr *, and then exits. Your responsibility is to provide 
reasonable values for N, Mt, and Columns. See the Discussion section for more details, 


Sample Usage 
program Samp] eUsage0fShow2Arr; 
const, 

ColSize = 2; 

RowSize = 108, 


type 
Array2Type = arvayl1..RowSize, 1, ColSize] of real; 


var 
Nun2Array > ArrayZType; 
RowCount, N, 4, Coluns : integer; 


($1 Show2Arr. PSL) 
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‘BEGIN 
NunZArrayCt,12 == 1.01, NuaZArrayC1,21 := 22.7, 
Nun2Arrayl2, 1] := 3.4; 
NunZArray€3, 1] = -8, 05; 
RowCount: '= 3; 
Nis 8 M:= 2; Columns = 2, 
Shou2Arr(NunZArray, RowCount, N, M, Columns), 
Now @ 
Show2Arr(NunZArray, RowCount, N, M, 2) 

END, 





‘The output of the sample program is a screen containing this first group of lines 
and then, after a key is pressed, the second group: 





(12 1a. 01,27 270 
(212 340 (2,2) -42. 00 
[3,1] -8.05 (3, 21-6666.66 
* Press a key to continue == 


(1,11 1, @1@eoaede+ae 1,23 2. 27@@000RORETOL 
(2,11 3. 400aeeg@edE+22 2, 2) ~4. 2@00000@RErOL 
[3,11 -5, aaao@@q@eE-22 (3, 2] -6. 6666600006403 
Press a key to continue ** 


Subprogram Listing of Show2Arr.PSL 
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Variables 

Rous Number of rows (lines) that may be displayed on one 
sereen 

J Subscript that varies from 1 to RowCount, indicating the 
current row being displayed 

K Subscript that varies from 1 to ColSize, indicating the 
column of the array (not the screen) being displayed 

LastElement Total number of elements in the array 

PageSize ‘Total number of elements that fit on one screen 

ElementCount Counter indicating how many elements have been shown, 
Because the counter begins with the number 0 (zero), 
ElementCount represents the next clement to be shown, 
not the current one. 

Coluidth Width of each column. The width is based on the value 
of N. 

NumOnPage Counter indicating how many elements have been shown 
‘on the current screen. NunOnPage ranges from zero 10 
PageSize - 1 

Discussion 


A number of ways are available for displaying on the screen the contents of a two- 
dimensional array. This subprogram provides one way, allowing you some control 
with the parameters you provide. The Modifications section suggests some changes 
to this method. The intent is to make the subprogram easily understood yet flexible 
‘enough so that you can apply it in different circumstances. 


Columns can be any integer from 1 to 8, depending on what value you provide for 
NIEN is zero, you are requesting that your values be displayed in floating-point 
format, and Columns should be no larger than 3. IfN is greater than zero, Columns 
should be no larger than 80/(N + 9). 


The main for-do loops increment J and K through each row and column in the 
array. The other variables and constants keep track of where cach element goes 
‘on the screen and whether the screen is full yet, 
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Modifications 


1. To change the number of rows (lines) displayed on each screen before 
waiting for a key to be pressed, change the value in the statement 
indicated by (Mod. #19. Rows can be any integer from 1 to 24, 


2. Eliminate the display of the element numbers by deleting the second 
line indicated by (Mod. #2). Then, if you like, change the first line 
indicated by (Mod, #2) to 


ColUidth «=N+1; 


This allows more columns to be displayed on cach screen. With this 
second change, Columns should be no larger than 80/(N + 1). 
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Using the Printer 





Routing normal text to a printer is straightforward in Turbo. You simply use the 
preassigned file Ist in your write and writeln statements, as explained in the 
Turbo manual, 


In this chapter are subprograms that create nonstandard effects with your printer. 
‘Three of the programs print text in a special way. You can get underscored text 
with UnderSe, boldfaced text with Bol dFace, or overstruck text with StrikeOv. 


NeuPage form-feeds the printer. This causes the current page to eject and the next 
page to be positioned for printing (assuming that you are using continuous-roll or 
fan-feed paper) 

nally, PrtSe makes a printed copy of the current screen contents. This task is the 
same one accomplished by the Shift-PrtSc key combination, but here it is done 
within a Turbo program. Graphics screen images can be produced if your printer 
supports a graphics-emulation mode. 

The subprograms use standard printer ASCII codes to accomplish special effects. 
“These codes are supported almost universally by today’s hardware. The subprograms 
should work with all of the popular printers. 








UnderSc 





Name: UnderSc 
‘Type: char function 
Purpose: To print underscored text 
Calling Sequence: UnderSe(WorkStr) 
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Description 
UnderSe enables the printer to underscore printed text. The function is designed 
for use inside a write or writeln statement directed to the printer through Turbo's 
preassigned Ist file. Underscored text can be freely mixed with nonunderscored 
text in the same write statement. 

Input 


WorkStr string The text to be printed and underscored. It can be 
specified as a string variable (of any string type) or 
as a text literal 


In addition, the following global type declaration must appear in your main program: 


type 
String255 = stringCZ553, 


Output 
WorkStr is printed and underscored on the printer. 


Limitations and Error Conditions 


IfUorkStr is null, a space character followed by a backspace is sent to the printer. 


‘This creates no net effect unless the printer is positioned at its last print position 
before the call to UnderSe, 





If UnderSe is used in a write statement not directed to the printer (that is, without 
the Ist file designation in the write statement), UorkStr is still routed to the 
printer, Subsequent text in the same write statement is also sent to the printer, 


The printer must be on-line, or the system pauses to wait for the printer to come 
on-line. 


Sample Usage 
Program SampleUsage0fUnderSe; 
type 


String255 = stringt2552, 
StringType = stringl2a3, 
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var 
UorkStr + StringType; 
AreaCode * integer; 


($I UnderSc. PSL) 


BEGIN 
writeln(Ist, “Respond ’, UnderSc(’ immediately’), ‘ please.‘ ); 
writeln(1st), 
AreaCode «= 212; 
str(AreaCode, WorkStr); 
uriteln(Ist, ‘Call Dave at area code “, UnderSc(WorkStr)); 
writeln(1st); 
str(pi:816, WorkStr), 
writeln(Ist, “Pi =“, UnderSe(WorkStr), ’ approximately’ 
END. 


Figure 5.1 shows the result of running this program with an EPSON MX™-80 printer 
attached to a standard IBM PC. 


Respond i 





ely please. 


Call Dave at area code 212 


Fig. 5.1. The program output illustrating the use of UnderSe 


Subprogram Listing of UnderSc.PSL 
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Variables 
J Loop index 
WorkLen ‘The string length of WorkStr 
Discussion 
In the following comments, references to Turbo's write statement apply to writeln 
as well. 


UnderSe is intended for use with write statements directed to the printer. Each 
write statement should send output to the printer through Turbo's preassigned 
1st file, That is, the write statements should begin like this: 





wr Is 


Except for the underscoring, the operation of each write statement is normal, Print 
head positions retain their expected values, and nonunderscored text can be freely 
mixed with the underscored text. See the Sample Usage program for some examples. 


UnderSe accepts only string arguments. You can, however, get the value of a real 
or integer variable underscored. Use Turbo's str procedure to convert the value 
of your numeric variable (or constant) to a string (using format descriptors if you 
want), The call to str precedes the call to UnderSe. Then use UnderSe as usual. 
‘The Sample Usage program demonstrates this technique. 


‘The normal ASCII codes for backspace (#8), underscore (#95), and space (#32) 
are used. Nearly all of today’s popular printers support these codes. and UnderSc 
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The method UnderSe uses is interesting. The “natural” way to design UnderSe is 
as a procedure instead of a function; unfortunately, procedures cannot be called 
within write statements. Functions can, however. To achieve underscoring, you 
must therefore design UnderSc as a function. A problem arises in that any function 
must return a value. Any value returned by UnderSe is sent to the printer (causing 
undesirable print). 





You can use a trick to achieve the desired effect. Once “inside” the UnderSe sub- 
program, you can call procedures, Thus, write statements directed to the printer 
(through Turbo's standard Ist file) are used by UnderSe, UorkStr is printed, the 
appropriate number of backspaces are issued, and underscores are printed. Next, 
‘one extra backspace character is “printed.” UnderSe then returns a space character 
(#32) as its char functional output, causing the original write statement to print 
one blank character. This positions the print head exactly where you want it with 
the correct underscoring accomplished. (If WorkStr is null, the algorithm is slightly 
modified.) 











Modifications 


None 


BoldFace 
Name: Boldface 
Type: char function 
Purpose: To print boldfaced text 
Calling Sequence: Bol dFace(WorkStr) 














Description 
Bol dFace enables the printer to print boldfaced text. The function is designed for 
use inside a write or writeln statement directed to the printer through Turbo's 
preassigned Ist file. Boldfaced text can be freely mixed with regular text in the 
same write statement. 


Input 
UorkStr string The text to be printed in boldface. The text can be 


specified as a string variable (of any string type) or 
as a text literal. 
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In addition, the following global type declaration must appear in your main program: 


type 
String255 = stringl2551; 


Output 
WorkStr is printed in boldface on the printer. 


Limitations and Error Conditions 


If UorkStr is null, a space character followed by a backspace is sent to the printer, 
‘This creates no net effect unless the printer is positioned at its last print position 
before the call to Bol dFace. 





Ifyou use Bol dFace in awrite statement not directed to the printer (that is, without 
the Ist file designation in the write statement), UorkStr is still routed to the 
printer. Subsequent text in the same write statement is also sent to the printer, 





The printer must be on-line, or the system pauses to wait for the printer to come 
on-line. 


Sample Usage 
Program SampleUsageOfBol dFace; 


type 
String255 = stringl2553, 
StringType = stringC203, 


var 
UorkStr: StringType; 


($I BoldFace. PSL) 


BEGIN 
UorkStr <= ‘Wednesday’; 
writeln(ist, ‘It is due’, BoldFace(WorkStr), * by noon.’ ); 
writeln(1st); 
writeln(Ist, “This line ends with ’, BoldFa 
writeln(1st); 
str(memavail, WorkStr); 


writeln(st, BoldFace(WorkStr), “ paragraphs left on heap.‘ ) 
END 





( boldface.’ )); 
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Figure 5.2 shows the result of running this program with an EPSON MX-80 printer 
attached to a standard IBM PC. 


It is due Wednesday by neon. 
This line ends with boldface. 


23572 paragraphs left on heap. 


Fig. 5.2. The program ouput illustrating the use of B0\ Face 


Subprogram Listing of BoldFace.PSL 
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Variables 
NuaReps Number of times to overprint UorkStr 
AK Loop indices 
UorkLen ‘The string length of UorkStr 
Discussion 
In the following comments, references to Turbo’s ur ite statement apply to writeln 
as well 
Bol dFace is intended for use with write statements directed to the printer. Each 





urite statement should send output to the printer through Turbo’s preassigned 
Ist file. That is, the write statements should begin like this: 


wr 





1s 


Except for the bokdfucing. the operation of each write statement is normal, Print 
head positions retain their expected values, and regular text can be freely mixed 
with the boldfaced text, See the Sample Usage program for some examples 


Bol dFace accepts only string arguments. You can, however, get the value of a real 
‘or integer variable boldfaced. Use Turho's str procedure to convert the value of 
Your numeric variable (or constant) to a string (using format descriptors if you 
want), The call to str precedes the call to Bol dFace. Then use Bol dFace as usual 


‘The normal ASCH codes for backspace (#8) and space (#32) are used. Nearly all 
‘of today’s popular printers support these codes, and BoldFace should work on 
‘almost any system. 


BoldFace works by printing the desired text, backspacing, and then printing the 
text again. A programming trick was used in order to call Bol dFace within a ur ite 
‘statement. This trick is explained in the Discussion section for UnderSe. 











Modification 


Minimally, boldfaced text is produced by a single overprinting, If you need darker 
text, you may try additional overprintings to sec the effect on your printer. ‘The 
‘number of overprintings is controlled by the constant NusReps in the line denoted 
bby (Hod. #1. You may make NusReps any positive integer. 
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StrikeOv 





Name: StrikeOu 
Type: char function 
Purpose: To print overstruck text 
Calling Sequence: Str ikeOv(WorkStr) 








Description 


StrikeOu enables the printer to print text and then strike it out by overprinting 
hyphens. Overprinted text is necessary in many legal documents. StrikeOv is de- 
signed for use inside a write or ur iteln statement directed to the printer through 
‘Turbo's preassigned Ist file. Overstruck text can be frecly mixed with regular text 
in the same ur ite statement. 





Input 


WorkStr string ‘The text to be printed and overstruck. It can be 
specified as a string variable (of any string type) or 
as a text literal 


In addition, the following global type declaration must appear in your main program: 


typ 
String2S5 = stringt 255, 
Output 
UorkStr is printed and overstruck on the printer. 


Limitations and Error Conditions 


If WorkStr is null, a space character followed by a backspace is sent to the printer. 
‘This creates no nct effect unless the printer is positioned at its last print position 
betore the call to Str tkeDs. 


Ifyou use Str ikeOy in aur ite statement not directed to the printer (that is, without 
the Ist file designation in the write statement), UorkStr is still routed to the 
printer. Subsequent text in the same write statement is also sent to the printer. 


‘The printer must be on-line, or the system pauses to wait for the printer to come 
on-line. 
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Sample Usage 
program SampleUsageDfStrikeOu; 
type 
String255 = stringl255); 
StringType = stringl2@3; 
var 
UorkStr: StringType; 
($1 StrikeOv. PSL) 
BEGIN 
uriteln(lst, “JOHNSON “, StrtkeOQu(’ AND JONES’), “ ALLEGEDLY’ ); 
writeln(st); 


str (1991, UorkStr); 
writeln(lst, “Design is due in’, StrikeOv(UorkStr), ° 1987) 


Figure 5.3 shows the result of running this program with an EPSON MX-80 printer 
attached to @ standard IBM PC, 


JOHNSON ANB-d8NES ALLEGEDLY 
Design is due in #99% 1989 


Fig 5.3. The program owipust iiustrating the use uf Ste ined 


Subprogram Listing of StrikeOv.PSL 
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Variables 
J Loop index 
UorkLen ‘The string length of UorkStr 
Discussion 
In the following comments, references to Turbos wr ite statement apply to wr iteln, 
as well. 


Str {keOv is intended for use with write statements directed to the printer, Each 
urite statement should send output to the printer through Turbo's preassigned 
Ist file. That fs, the write statements should begin like this: 


write(lst, 


Except for the overprinting, the operation of cach write statement is normal, Print 
head positions retain their expected values, and regular text can be freely mixed 
‘with the overstruck text. See the Sample Usage program for some examples, 


StrikeOv accepts only string arguments. You can, however, get the value of a real 
‘or integer variable overprinted. Use Turbo’s str procedure to convert the value 
of your numeric variable (or constant) to a string (using format descriptors if you 
want). The call to str precedes the call to StrikeOv. Then use Str ikeOv as usuitl 
‘The Sample Usage program demonstrates this technique. 

‘The normal ASCII codes for backspace (#8), hyphen (#45), and space (#32) are 


used. Almost all of today’s popular printers support these codes, and Str ikeu 
should work on almost any system. 
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‘The same trick explained in UnderSe is used to accomplish the overprinting, See 
the Discussion section of UnderSe for details. 

Modification 
Instead of using hyphens, you may want to overprint with some other character. 


Just change the ASCII code from #45 (hyphen) to whatever character you want. 
Make this change in the line denoted by (Hod. #12 


NewPage 


Name: NewPage 





‘Type: Procedure 
Purpose: To cause the printer to eject to the next page 
Calling Sequence: NeuPag: 











Description 


This procedure causes the printer to form-feed continuous paper so that subsequent 
printing begins at the top of the next page. 


Input 


None 


Output 


The printer ejects the current page and positions the next page for printing. 


Limitations and Error Conditions 


NewPage works as intended only on printers using continuous-roll or fan-feed paper, 
‘The printer must be on-line, or the system pauses to wait for the printer to come 
online 
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Sample Usage 
program SampleUsageOfNewPage; 


($I NewPage. PSL) 
IN 
uriteln(Ist, “Printing on top of page 1°); 
uriteln(lst, ‘Printing on second line of page 1°); 


NewPage; 
writeln(Ist, “Printing on top of page 2) 


Running this test program causes the following two lines to print on the current 
page in the printer; 


Printing on top of page 1 
Printing on second line of page 1 


“The current page is then ejected, and the printer form-feeds the paper, The following 
line is then printed at the top of the new page: 


Printing on top of page 2 


Subprogram Listing of NewPage.PSL 





Variables 


None 


Discussion 
‘This procedure is useful when you are printing reports or other documents that 
need to be adjusted to new pages. 
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Modification 


Almost all of today’s printers use ASCII 12 (decimal) as the form-feed character. 
If you have a printer that doesn’t conform to this standard, change the #12 in the 
line indicated by (tod. #1) to the value required for a form feed. 


PrtSc 





Name: Pric 
Type: Procedure 
Purpose: To print a copy of the current screen contents 
Calling Sequence: PrtSe 








Description 


By pressing the Shift-PriSe keys on an IBM PC, you send to the printer an image 
oof the current screen. PrtSe does the same thing from within a Turbo program, 
‘A “’snapshot” copy of the current sereen is printed. You can use PrtSe for graphics 
images as well as for regular text. See the Discussion section. 


Input 


None 
Output 
A copy of the current screen contents is routed to the printer and printed. 


Limitations and Error Conditions 


‘The printer must be on-line, of the system pauses to wait for the printer to come 
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Sample Usage 


program SanplaUsageOfPrtSc, 
($1 PrtSe, PSL) 


BEGIN 

clrser; 

uriteln(’ This 1s line nunber 1°); 

uriteln(’This 1s Line nuaber 2); 

gotory(t, 10), 

uriteln(’ This ts line number 12), 

PrtSe; 

writeln(’ This should not print on the printer’) 
END. 


The results of this sample program are shown in figures 5.4 and 5.5, Figure 5.4 
shows the output on the line printer, and figure 5.5 shows how the screen appears. 
Notice the additional line seen on the sereen but not on the printer. This line does 
hot appear on the printer because the call to PrtSe is made before the line is 
displayed, 





This is line number 1 
This is line number 2 


This is line number 10 


Fig. Sch. The ouput of the PetSe demonstnation program as it agyrears on Ube printer 





This is line number 1 


This is line number 2 


This is line number 10 
This should not print on the printer 


Fig, 5.5. The output of the PrtSe demonstration program as it appears on the screen. 
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Subprogram Listing of PrtSc.PSL 





Variables 


None 


Discussion 

You can use this subprogram to create images of a graphics screen while your 
program is in one of Turbo's graphics modes. To create such images, you need the 
proper hardware and software. You must be running DOS V2.0 or higher. From 
DOS, you must execute the program GRAPHICS.COM before you enter Turbo. 
GRAPHICS.COM is supplied by IBM with DOS V2.0 and higher. This program en- 
ables the normal Shift-PrtSe key sequence to work with graphics screens. In addition, 
your printer must be capable of a graphics mode. The IBM 80 CPS Graphics Printer 
and compatibles (including most EPSON printers) have this capability. 

PrtSe works by generating the system's Shift-PriSc function through a ROM BIOS 
call, In Turbo, the intr procedure invoking interrupt 5 performs this task. 


Modifications 


None 





Manipulating Disk Files 





Disk configuration is a critical element in any computer system. Data cannot remain 
in RAM (random-access memory) forever, and most people who use a computer 
for any practical purpose find that they give their disk drive(s) a heavy workout. 
‘This chapter presents a dozen subprograms to help you make good use of your 
disks. 


First, a word about the filespec is necessary. A filespec (file specification) is a semi- 
official term that sometimes refers to a disk drive and file name and at other times 
includes the directory path to get to the file. As the term is used here, a filespec 
consists of four elements (of which three are optional) in the form 
D:\PATH\FILENME. EXT. The D> specifies the disk drive, which is either A: or B 
for floppy disks, or gencrally C* for a fixed disk. The \PATH\ is the subdirectory 
route through which DOS finds the file. If you never use subdirectories, you can 
omit the path and the surrounding backslashes. The FILENAE and . EXT make up 
the actual name of the disk file, following the rules in the DOS manual. Only the 
FILENAE portion of a filespec is required; D' and \PATH\ are needed only if the 
current default disk drive and path do not lead to your file, and . EXT is needed 
only if your file was named with an extension, Most of the programs in this chapter 
tuse a filespec in one form or another. 


‘The subprogram DiskSp deals with an entire disk (not just one file) and reveals 
how much space is available on that disk. VerDisk is also global rather than file 
oriented; it sets the DOS disk verify switch on or off 


ShouDir and NextFile work with a disk directory. ShouDir displays a directory's 
contents, and NextFile finds in the directory the next file name subject to your 
specifications. Filelnfo and FileDel deal with a single disk file, Filelnfo obtains 
information about a disk file (size, date and time updated, and attributes). Fi 1eDel 
provides a simple way to delete a file. 

‘The remaining six subprograms save and load disk files from and to three types of 
arrays: (1) one-dimensional real or integer (Savefrr and Loadfrr), (2) two 
dimensional real (Save2Arr and Load2Arr), and (3) text or string (SaveTxt and 
LoadTxt). 
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Purpose: To determine bow much disk space is available 
Calling Sequence: DiskSp(DiskNun, BytesFree, BytesCluster, BytesCap) 











Description 


DiskSp uses a DOS function call to determine the number of bytes of free space 
available on the disk in the drive you specify, as well as the size of a cluster in 
bytes and the capacity of the disk in bytes. These values are useful indicators of 
the current status of a disk and are quite handy in many types of programs that 
store and track disk data. 





Input 


DriveNun integer The drive number of the disk you are inquiring 
about. Zero indicates the default disk drive, 1 
indicates drive A, 2 indicates drive B, and so on, 


Output 
BytesFree real The number of bytes free (unused) on the disk 
BytesCluster real ‘The number of bytes in a cluster (allocation 
unit) on the disk 
BytesCap real The capacity of the disk in bytes (that is, the 
Aumber of clusters times the size of each 
cluster) 


Limitations and Error Conditions 


DriveNum must indicate a legal disk drive on your computer, Otherwise, all three 
Output values are set to -1 to indicate an error. Legal values for Dr iveNum are theo. 
Fetically 0 through 255. On a computer with two floppy disk drives, legal values 
are 0, 1, and 2. However, because only the low-order byte of DriveNum indicates 
the disk drive number, any value is acceptable if its low-order byte is a legal number 
For example, 257 and 513 are the same as 1, and 258 and 514 are the same as 2 
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Sample Usage 
program SampleUsage0fDi skSp; 


var 
DriveNum: integer; 
BytesFree, BytesCluster, BytesCap: real; 


(SI DiskSp. PSL) 


BEGIN 
DriveNum = 
DiskSp(DriveNun, BytesFree, BytesCluster, BytesCap); 
if BytesCap > @.@ then 


begin 
uriteln(’For disk drive number “, DriveNum), 


uriteln(BytesFrea:9'@,  * bytes free space’ ); 
uriteln(BytesCluster:9:@, ’ bytes per cluster’ ); 
uriteln(BytesCap 9/8, bytes disk capacity’) 
end 
else 
uriteln(’*s Error ~ illegal DiskSp request ** ) 





END. 


With our original Turbo Pascal compiler disk (Version 3.014) in the default disk 
drive, this sample program produces the following output (your Turbo disk may 
be different, perhaps because of changes in the README file): 





For disk drive number @ 

158728 bytes free space 
1024 bytes per cluster 

362496 bytes disk capacity 
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Subprogram Listing of DiskSp.PSL 





Variables 
Rog A record containing the standard IBM PC register names, 
Reg is used to pass values to and from Turbo's msdos 
procedure. 
Discussion 


‘This subprogram uses DOS function call 36 (hex) to retrieve information. The 
cluster is the fundamental allocation unit of DOS, If the cluster size is 1,024 bytes 
(as it is for double-sided floppy disks), then the smallest space a file uses is 1,024 
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bytes, even if the file is only 50 bytes long. To determine the number of bytes of 
free space, DiskSp multiplies the number of clusters available by the cluster size. 
Note that a disk actually has more free space than this calculation indicates, because 
each file generally has some free space available in its last cluster, This “phantom” 
free space, however, is available only if you expand the file a little (without going 
beyond that last cluster boundary) or if you combine several small files into one 
large file, thus trading several partially empty clusters for one. 


Modifications 
None 


VerDisk 


Name: VerDisk 
‘Type: Procedure 
Purpose: To turn the DOS disk verification switch on or off 
Calling Sequence: VarDisk(Ver ify) 








Description 
‘This subprogram turns the DOS “verify” switch on or off, depending on whether 
the Ver ify parameter is true or false. The same actions can be done with the DOS 
VERIFY command, but VerDisk provides a method of setting this switch from a 
Pascal program. The verify switch is off by default. Turning the switch on causes 
DOS to perform a verify operation after each disk write, thus checking that the 
written data is correctly recorded. 


Input 
Verify boolean Setting for the verify switch. A true value causes the 
switch to be set on. A false value causes the switch 
to be set off 
Output 


Disk verification is activated or deactivated as requested. No variables are changed. 
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Limitations and Error Conditions 

In the disk-verify operation, DOS does not actually reread the data just written on 
disk and compare that data with the data in memory. Instead, the verify operation 
looks for a mismatch of the cyclic redundancy checks (CRC), which do not match 
if data was incorrectly recorded. Although such errors occur rarely (and the ver- 
ification process lengthens disk writing time), some people like to be cautious with 
certain critical data. Turning the verify switch on is one way to be cautious. Once 
‘set on, disk verification remains on until it is turned off by cither the DOS VERIFY 
‘command or a program that invokes the same DOS call used by VerDisk, 


Sample Usage 
Program SampleUsageOfVerDi sk; 


var 
Verify: boolean; 
(SI VerDisk. PSL? 


EOIN 
Verify ‘= true; 
VorDisk (Verity), 
If Verify then 
writeln(’ Disk verify is now on’) 
else 
writeln(’ Disk verify ts now off’) 


‘This program tums disk verification on (even if itis already on) and displays the 
following message: 


Disk verify 1s now on 


Subprogram Listing of VerDisk.PSL 
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Variables 
Reg ‘A record containing the standard IBM PC register names. 
Reg is used to puss values to Turbo's msdos procedure. 
Discussion 


‘See both the Description section and the Limitations and Error Conditions section, 


Modifications 


None 


ShowDir 
Name: ShowDir 
Type: Procedure 
Purpose: To display a directory or subdirectory on the screen 
Calling Sequence: ShowDir(FileSpec, Attr) 














Description 
Depending on the file specification and attribute characteristics, the entries (fle 
names) in ansMS-DOS® (or PC DOS) disk directory or subdirectory are displayed 
‘on the screen, five entries per line. You can specify the default disk drive and 
directory, or another drive and subdirectory of your choice You can specify all 
files, including system and hidden files, or only normal file entries. The global 
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‘characters * and ? are allowed in the file name and extension portion of the filespec. 
DOS V2.0 or higher is required. 


Input 


FileSpec string A standard DOS filespec in the form 
D:\PATH\F ILENE. EXT, indicating the files you want 
displayed. The current directory is assumed if the 
disk drive (D:) and path are omitted. Global 
characters (? and *) may be used in the file name 
and extension. The path portion of FileSpec cannot 
exceed 63 characters, and the total length of 
FileSpec cannot exceed 79 characters. 


attr byte —_A byte with bits sct to indicate the attributes of the 
files you want displayed, as explained in two places 
in the IBM DOS V2.0 manual (other versions of DOS 
‘may have the explanations elsewhere): (11) Appendix 
C, where the “file attribute” is explained in the DOS 
Disk Directory section, and (2) Appendix D, in the 
discussion of DOS function call 11 hex. Zero 
indicates only “normal” files (no hidden or system 
files and no subdirectories). Hex 10 adds 
subdirectories. Hex 16 shows normal, hidden, and 
system files, plus subdirectories. Hex 10 is usually 
what you will want. 


In addition, you must code in your main program the following global type 
declaration: 











Output 


‘The entries in the specified directory or subdirectory are displayed on the screen 
in five columns. Subdirectory names, if requested by Attr, are indicated with (D2 
before the name. 


Limitations and Error Conditions 


‘The starting message ** Directory listing for CFileSpec] ** is always dis- 
played. If the specified directory or subdirectory is empty or does not exist, or 
if no files match the FileSpec and Attr requirements, then the message 
‘#No filenames found, ** is displayed, and the subprogram terminates. Otherwise, 
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the terminating message is ** End of directory listing. **. DOS V2.0 or higher 
is required for this subprogram. 


Sample Usage 


program SamplaUsage0fShouDir; 





type 
String8@ = stringC8@3, 

var 
FileSpec * String8d; 
Attr «byte; 

(SI ShouDir. PSL) 

BEGIN 
FileSpec °*‘*.*'; 
Attr —s= $19; 


ShouDir(FileSpec, Attr); 
writeln(’= ~~ - ~"); 
FileSpec == ‘B:\MONTHLY. DAT\= #”; 
ShouDir(FileSpee, Attr) 

END, 





If a test disk is in the default disk drive (B:) and the root directory is set as the 
current directory, the Sample Usage program first displays the root directory, then 
a subdirectory. A line of five hyphens is displayed between the two directory listings. 








** Directory listing for *.* 
INDEX. DAT COIMONTHLY. DAT MONTH. PAS zon z 
2 ‘ZSUBPGHS. PAS © ZSUBPGMS. DAT RECAP. DAT 

w* End of directory listing ** 

Directory listing for B’\MONTHLY. DAT\*. « 

03. co. AHL DAT FEB. DAT 


w+ End of directory listing, 


Subprogram Listing of ShowDir.PSL 
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Variables 
Columns Constant 5. This is the number of columns on the screen. 
J Subscript used to extract file name from DTA 
ColSize Size (width) of screen columns. With 5 columns, ColSize 
is 16. 
Reg Record of registers for use in calling the msdos procedure 
DTA Disk transfer area, as required by DOS function calls 
Discussion 


If you write a program that requires a user to enter a file name, you usually want 
the files in a directory to be displayed first. If your program processes an input file, 
the user needs to see the existing file names in order to choose the correct one. 
If your program creates an output file, the user needs to see the existing file names 
to be able to choose a new, nonduplicate name. This subprogram displays a directory 
by making use of several PC DOS function calls. First, the subprogram uses call 
hex 1A, telling DOS where the disk transfer area is, Then the subprogram turns 
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the Fi leSpec string into an ASCIIZ string (a special kind of string required by some 
DOS function calls) by adding a zero byte at the end, 

Function call 4E (hex) finds the first entry that matches the ASCIZ string. If no 
‘match is found (indicated by a nonzero return code in the low-order byte of the 
AX register), a message is displayed, and the subprogram ends. If a match is found, 
the file name is returned by DOS, beginning in the 31st byte of the DTA, Then 
function call hex 4F is used to find all the remaining entries that match the request. 
Each matching file name is displayed in tum, five names per line, until no more 
names can be found. 

Function calls 4E and 4F are available only in DOS V2.0 and higher. Earlier versions 
of DOS require the use of function calls hex 11 and 12 instead. 


Modifications 


1. The number of columns displayed on the sereen can range from 1 to 5. 
‘Simply change the number in the line denoted by (Mod, #1) 


2, This subprogram assumes that you are using an 80-column display. To 
convert the subprogram to a 40-column display, change 88 to 49 in the 
line indicated by (Mod. #2). You also need to use the first modification 
to indicate either one or two columns, unless you can be sure that all 
file names on your disks are short. (That is, no file names have more 
than nine characters for three columns, six characters for four columns, 
and four characters for five columns, These limitations are based on the 
assumption that directory entries may be specified. Otherwise, add three 





to the lengths.) 
NextFile 
Name: NextFile 
Type: Procedure 
Purpose: To find the name of the next file in a disk directory 
Calling Sequence: NextFile(FileSpec, Attr, Code, Name) 








Description 


Depending on the FileSpec and Attr (attribute) you specify, the next matching 
file name in an MS-DOS (or PC DOS) disk directory or subdirectory is returned 
in Name. You can specify the default disk drive and directory, or the drive and 
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subdirectory of your choice. You can use the global characters ? and *, as in DOS 
‘commands. DOS V2.0 or higher is required. NextF ile is useful for scanning a disk 
directory to find files with certain names or characteristics. 


Input 


FileSpec string 


attr 


Code 


byte 


integer 


A standard DOS filespec in the form 

1D: \PATH\FILENA'E. EXT, indicating the files you want 
found. The disk drive (D:) and path are optional. The 
file name may contain ? and/or *. The total length of 
FileSpec cannot exceed 79 characters, and the path 
‘cannot exceed 63 characters. Details about paths and 
file names are in the DOS manual 


A byte with bits set to indicate the attributes of the 
files you want found. For details, see the Input 
section of ShosDlir. Zero indicates “normal” files only, 
Hex 10 includes subdirectories too, Hex 16 includes 
also hidden and system files. 


‘A numeric value that indicates the action you want 
taken. Zero indicates that this is the first request 
(that is, find the first file). One indicates a 
subsequent request (find the next file). 





In addition, you must code in your main program the following global type 


declarations: 








type 
String8@ = stringt82J; 
StringlS = stringl15); 


Output 
Code 


integer 


string 


Code is set to 1 if.a file name was found to match 
your request, or 2 otherwise 

A 15-character (maximum) string with the name of 
the file found. This string includes a period between 
the 8-character name and the 3-character extension, 
if any. If the name is a directory entry, Name has CD 
in the first 3 positions, followed by the directory 
‘name. 
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Limitations and Error Conditions 


Code is set to 2 when no matching file name can be found, whether on the first 
request or subsequent requests. This subprogram sets up a DTA (data transfer area) 
into which DOS places the file name data. Your program cannot take any action, 
such as opening a file, between calls to NextFile if the action might change the 
DTA. If your main program affects the DTA between uses of NextF ile (for example, 
by opening and reading from cach file as you find matching names), use NextF ile 
to save in an array all the matching file names. Then retrieve each file name from 
the array before opening the file. For an example of saving file names in an array, 
see the full program SortDir in Chapter 18. 


Sample Usage 
Program SampleUsageOfNextF ile; 
type 


String8@ = stringl8d: 
Stringi5 = stringCt5], 





var 
FileSpec * String8@, 
Name StringiS, 
attr byte; 
Code Integer; 


(SI NextFile. PSL) 








BEGIN 
FileSpec ” 
attr = 510, 
Code 
repeat 


NextFile(FileSpec, Attr, Code, Name); 
if Code = 1 then 
urite(Name: 16) 
until Code <> 4, 
writeln 
END. 


‘With a test disk in disk drive B (the default drive at the time), this sample program 
displays the following output: 


INDEX. DAT CDJHONTHLY. DAT MONTH. PAS 2PoH 


Subprogram Listing of NextFile-PSL 
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Variables 
J Subscript used to extract the file name from DTA 
Reg Record of registers for use in calling the msdos procedure 
BTA Disk transfer area, as required by DOS function calls 
Discussion 


NextFile uses the same DOS function calls that ShowDir uses. See the Discussion 
section of ShowDir for details. 


Modification 


NextFi le indicates a directory entry with CD) in the first three characters of Name. 
‘Change CD1 in the two indicated lines to any other string of one to three characters, 
‘or to null (two apostrophes with no space between) in order to eliminate any 
differentiation between directories and file names. 


FileInfo 


Name: Fileinfo 
Type: Procedure 
Purpose: To obtain information about a specified disk file 


Calling Sequence: FileInfo(FileSpec, FileBytes, Yr, Hon, Day, Hr, Hin, 
Sec, AttrList) 











Description 
‘The FileInfo subprogram returns certain information about a disk file: the size of 
the file (in bytes), the date and time the file was last updated, and the attributes 
of the file, All this data is obtained from the disk directory through a DOS function 
call 


Input 
FileSpec string A DOS file specification in the standard form 
D:\PATHFILENYE EXT. If the disk drive or path is 
omitted, the current default disk or current directory 
is used. The global characters * and ? can be used in 
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the file name, but they are not generally useful 
because the subprogram does not return the file 
‘name found. The intent of the subprogram is to 
‘obtain the information about a specific file. 


In addition, you must specify in your main program the following global type 
declarations: 






type 
String§@ = stringt6a, 
StringS = stringC53, 


Output 
FileBytes real The number of bytes in the disk file. This value is 
“1.0 if no file is found to match the Fi l@Spee. 
Yr byte The year the file was last updated (0-99) 
Mon byte ‘The month the file was last updated (1-12) 
Day byte The day the file was last updated (0-31) 
Hr byte The hour the file was last updated (0-23) 
Nin byte The minute the file was last updated (0-59) 
Sec byte ‘The second the file was last updated (0-58), Sec is 


always an even number. 


AttrList string A five-byte string containing a character for cach 
attribute the file may have, For ease of use, each 
attribute always occupies the same position in the 
string (in alphabetical sequence). In other words, A, 
if present, is always in the first position; D, if present, 
is always second, etc. Here are the meanings of the 


attributes: 
A The file’s archive bit is set. 
D The file is a subdirectory. 
H This is a hidden file. 
R The file is read-only. 
S This is a system file 
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Limitations and Error Conditions 


If no match for FileSpec is found on disk, then FileBytes is set to -1.0, and the 
subprogram returns control to your main program; the other output values are 
invalid. The year of last update (Yr) is set to 80 through 99 for the years 1980 
through 1999, and 0 through 99 for the years 2000 through 2099. (That's right, 
when the year 2080 comes, Filelnfo will return the year 80 for a file, and you 
won't know whether that means 1980 or 2080. Feel free to write us a letter of 
complaint at that time.) In the time-of-day value, the number of seconds is saved 
by DOS as the number of 2-second intervals. Thus, the See value returned by 
Filelnfo can be an even number only. FileSpec must be no more than 79 bytes 
Jong; the path portion cannot exceed 63 bytes. 


Sample Usage 
Program SampleUsage0fFilelnfo; 


type 
String8@ = stringC9@2, 
StringS * string(S3, 


var 
FileSpec 
FileBytes 
Yr, Mon, Day, Hr, Min, See 
AttrList 





(SI Filetnfo. PSL) 


BEGIN 

ropeat 
uriteln(’ Enter FileSpec (or CEnter] to end)" ); 
readin(FileSpec), 
1f length(FileSpec) = @ then exit, 
Filelnfo(FileSpec, FileBytes, Yr, Hon, Day, Hr, Min, Sec, 

AttrList); 
if FileBytes < 9.8 then 
writeln(FileSpec, ° not found’ ) 

else 


Lai 


8 
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END. 


begin 


writeln(’ For FileSpec *, FileSpec); 


uriteln(FileBytes 8:8, " bytes file size’), 


writeln(Yr, "~", Mon, ‘~", Day, * last update date’ 
writeln(Hr, ‘=’, Min, “:, Sec, ‘ last update time’ 
uriteln( Attributes =’, AttrList) 


and; 
writeln(’- - - ~~) 
until length(FileSpec) = @ 





‘This sample program is handy to have available when you are running Turbo Pascal. 
‘The program provides a way to check the date and time you last updated the files 
You are working with. For the sample ourput that follows, the Turbo compiler disk 
(3.014) is in disk drive A. The system files for PC DOS V2.0 are also on the disk. 
Ifyou are using different versions of Turbo or PC DOS, your output will be somewhat 
different. In addition, if you have run the TINST utility on your Turbo disk, the 
date and time of that update will be reflected. Note the result of running Filelnfo 
‘on the file IBMBIO.COM (which you normally don’t see in a directory listing). The 
attributes show IBMBIO.COM to be a hidden, read-only, system file. In the sample 
‘output shown, the Enter key was pressed to end the program after the two file 
‘ames TURBO.COM and IBMBIO.COM were processed. 


Enter FileSpec 
A:TURBO.COM 
For FileSpec A: TURBO. COM 
39671 bytes file size 
85-4-17 last update date 
20:14 36 last update time 
Attributes = A 
Enter FileSpec 
A:IBMBIO.COM 
For FileSpec fA IBMBIO. COM 
4608 bytes file size 
83-3-8 last update date 
12:08 last update time 
Attributes = A HRS 


Enter FileSpec 


(or CEnter] to end) 





(or CEnter] to end) 





(or CEnter] to end? 


Subprogram Listing of Filelnfo.PSL 
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Variables 
Reg A record containing the standard IBM PC register names, 
Rag is used to pass values to and from Turbo's msdos 
Procedure. 
OTA ‘An array for the DOS data transfer area, in which DOS 
places the file information on request 
FD A record that redefines the DTA, simplifying the 
Processing of the file's size, date, time, and attributes 
Discussion 


To set up a data transfer area, Filelnfo invokes DOS function call 1A (hex), The 
DTA is then used by call 4E (hex) to retrieve the directory data for the specified 
file name. Parts of this directory data are the file’s size, date, time, and attribute 
information you want. Converting this information into numbers that Turbo Pascal 
‘can use is a little tricky. The file’s size (Fi leBytes ) is presented by DOS as a four- 
byte integer. The subprogram converts this integer into a real variable because 
‘Turbo doesn't support four-byte integers. The date and time of the last update 
require some strange-looking manipulation because DOS uses only a few bits of 
€ach byte to represent each component. Finally, the disk file's attributes are con- 
verted from five different bits in a single byte to the more convenient five-byte 
string AttrList, 
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Modifications 


None 


FileDel 





Name: FileDel 
‘Type: Procedure 
Purpose: To delete a disk file 
Calling Sequence: FileDel(FileSpec, Codi 











Description 


FileDel uses a DOS function call to delete the file indicated by FileSpec. If the 
deletion is successful, Code is set to zero. Turbo's erase procedure is another way 
to delete a file, but FileDel is easier to use: 


Input 
FileSpec string A DOS file specification in the standard form 
D:\PATH\FILENAE. EXT. If the disk drive or path is 
‘omitted, the current default disk or current directory 
is used. The global characters * and ? cannot be 
used. 


Inaddition, the following global type specification is required in your main program: 


type 
String8d = stringl823, 


Output 

Code integer A return code from the subprogram. Zero indicates 
that the specified file has been deleted. Other codes 
signify that no file has been deleted. If Code is 2, 
there is no such named file to delete. If Code is 5, 
the specified file cannot be deleted because access is 
denied. (That is, the file attribute indicates that the 
file is read-only.) 
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Limitations and Error Conditions 


‘The FileSpec string cannot exceed 79 characters, of which the path portion can 
be no more than 63 characters. The global characters # and ? cannot be used in 
the file name because of a restriction imposed by the DOS function call this sub- 


program invokes, 
Sample Usage 
program SampleUsage(fFileDel; 


type 
String8@ = stringC8a3, 


var 
FileSpec * String8@, 
Code + Integ 





(SI FileDel PSL) 


BEGIN 
FileSpec «= “A: TESTFILE. DEL’; 
FileDel(FileSpec, Co 
if Code = @ then 

uriteln(’File “, FileSpec, ’ deleted’) 
else 
uriteln(FileSpec, “ not 








ited. Code =“, Code) 





END, 


‘This test program produces the first of the following two messages if a file named 
TESTFILE. DEL is found and deleted from the current directory of the disk in drive 
A, and the second message if there is no such file to delete: 
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Subprogram Listing of FileDel.PSL 





Variables 
Reg A record containing the standard IBM PC register names. 
Reg is used to pass values to and from Turho's msdos 
Discussion 


Fi leDel makes use of DOS function call 41 (hex) to delete the specified file. There's 
nothing tricky here. The subprogram simply sets up the FileSpec as an ASCIZ 
String (by adding a hex zero at the end of the string), sets up the registers as 
required by DOS, and calls Turbo's msdos procedure. Then Code is set to the code 
‘returned by DOS. 


Modifications 


None 
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Purpose: To save an array’s contents onto a disk file 
Calling Sequence: Savefrr(Numfrray, Count, Code) 








Description 


Saver’ prompts you for a filespec, creates a disk file with that name, and then 
saves onto that disk file the contents of the real array NunArray. The companion 
Subprogram Loadfrr can later load the data back into an array. 


Input 
NumArray real Array in which the data to be saved is stored 
Count integer Number of elements occupied in the array 


In addition, you must specify in your main program the following global const and 
type declarations. The number 250 is an example. 





const 
frraySize 





250; 


type 
ArrayType = 





rrayCi. . ArraySize] of real, 


Output 


Code integer Error code from DOS. If Code is zero, the file was 
successfully saved on disk. Positive values are the 
decimal equivalents of the 1/0 error codes in 
Appendix G of the Turbo manual. Negative one (-1) 
indicates that the user canceled the request to save 
the array on disk. 

Savefirr creates an output disk file, using the filespec you enter at the keyboard 

while running the subprogram. After successfully saving the file, SaveArr displays 

a message showing how many elements were written to the 
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Limitations and Error Conditions 


If Count is less than 1, the subprogram is bypassed. If you enter a null filespec, 
Code is set to -1, and the rest of the subprogram is bypassed. Ifa file already exists 
with the same name you provide, the old file is replaced by the new file, If the 
file cannot be saved on disk, the subprogram beeps and displays Code with a message 
saying which I/O statement encountered the error (rewrite, write, or close), 
Code is the decimal equivalent of the hex I/O error number in Appendix G of the 
Turbo manual. For example, decimal 240 is hex FO, which indicates that the data 
area of the disk is full. (In other words, your files are too big.) Decimal 241 (hex 
FL) means that the directory is full. (That is, you have too many file names in the 
root directory, or the subdirectory does not exist.) 


Sample Usage 


program SampleUsageOfSaveArr; 





const 
frraySize = 252, 


type 
frrayType * arrayCt. .ArraySize} of real; (tod. #19 


var 
Numfirray © ArrayType; 
Count, Code * integer; 


($1 SavoArr. PSL) 


BEGIN 
for Count «+ 1 to 5 do 
NusfrrayCCount) = sgrt(Count);, 
Count == 5; 
Savefrrr(Nunfrray, Count, Code: 
if Code © @ then 
uriteln(’ Unsuccessful file save.’) 





‘This sample program produces the following output on the screen if you provide 
B:ARRAYTST.DAT as the filespec: 
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‘*» Enter filespec for output file, or == 
* press CEnter] key to cancel. “ 
B:ARRAYTST.DAT 

** 5 elenents written to file B:ARRAYTST. DAT 


If the directory being used is full before you run the sample program, the output 
looks like this instead: 








» Enter filespec for output file, or ## 
* press CEnter] key to cancel. “ 
B:ARRAYTST.DAT 

+ 1/0 error number 241(deciaal) = 

** from reurite In SaveArr. Aborted ## 
Unsuccessful file save. 


Subprogram Listing of SaveArr.PSL 
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Variables 
J Subscript variable 
FileSpec ‘Standard file specification for the output disk file 
TheF ile Internal file name in the subprogram 
Discussion 


Use this subprogram with LoadArr to transfer data between arrays in memory and 
disk files. Ifyou have two-dimensional arrays, use SaveZArr and Load2#w. To display 
the file names on disk before asking for the output file name, use the ShowDir 
subprogram in your main program just before invoking Savefr. 


Modification 
‘To convert this subprogram for use with integer arrays, change real to integer 
in the indicated statements in both the subprogram and the sample program. 
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Save2Arr 
Name: Save2Arr 
‘Type: Procedure 
Purpose: To save a two-dimensional array’s contents onto a disk file 
Calling Sequence: Save2Arr (Num2Array, RowCount, Code) 














Description 
Savefrr2 prompts you for a filespec, creates a disk file with that name, and then 


saves onto that disk file the contents of the two-dimensional real array. The com- 
anion subprogram Load2Arr can later load the data back into an array. 


Input 
Nun2Array real Array in which data is stored 
RowCount integer Number of rows of elements occupied in array 


In addition, you must specify in your main program the following global const and 
type declarations. ColSize is the exact number of columns (the second dimension) 
and is required. RowSize is the maximum number of rows (first dimension) and 
is not required as a constant. RowSize is recommended, however, as the Way to 
specify the type declaration. The numbers 2 and 100 are examples. 





Array2Type * arrayCi RowSize, 1. ColSize] of real; 


Output 


Code integer Error code from DOS. If Code is zero, the file was 
successfully saved on disk. Positive values are the 
decimal equivalents of the I/O error codes in 
Appendix G of the Turbo manual. Negative one (-1) 
indicates that the user canceled the request to save 
the array on disk 
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Save2Arr creates an output disk file, using the filespec you enter at the keyboard 
while running the subprogram. After successfully saving the file, Save2Arr displays 
a message showing how many rows were written to the file. 


Limitations and Error Conditions 


If RowCount is less than 1, the subprogram is bypassed. If you enter a null filespec, 
Gode is set to -1, and the rest of the subprogram is bypassed. If a file already exists 
with the same name you provide, the old file is replaced by the new file. If the 
file cannot be saved on disk, the subprogram beeps and displays Code with a message 
saying which I/O statement encountered the error (reurite, write, or close). 
Code is the decimal equivalent of the hex 1/O error number in Appendix G of the 
‘Turbo manual. For example, decimal 240 is hex FO, indicating that the data arca 
Of the disk is full. Decimal 241 (hex F1) means that the directory is full 





Sample Usage 
program SampleUsagefSave2Arr; 
const. 
ColSiz 2, 
RouSize = 108; 
type 


Array2Type * arrayC1..RowSize, 1,.ColSize) of r 





var 
NunArray ArrayZType; 
RowCount, Code, J © integer; 


($1 Save2Arr. PSL) 


BEGIN 
for RowCount ‘* 1 to 5 do 
for J == 1 to ColSize do 
NunZArrayCRowCount, J] «* Rowount * J; 
RowCount *= 5; 
SaveZArr(NuaZArray, RowCount, Code); 
if Code <> @ then 
uriteln( Unsuccessful file save’) 
END. 
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‘This sample program fills NumZArray with values equal to the product of the two 

for each clement. For example, element C1, 1] is 1 times 1, element 
3, 22 is 3 times 2, etc. The program produces the following output on the screen 
if you provide B:SAVEZTST.DAT as a filespec. (See subprogram Savefrr for sample 
output with an error condition.) 





x» Enter filespec for output file, or =* 
» press [Enter] key to cancel. “ 


B:SAVE2TST.DAT 
* 5 sets of 2 elenent(s) written to file B'SAVEZTST. DAT ## 


Subprogram Listing of Save2Arr.PSL 
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Variables 
J ‘Subscript variable for rows 
K Subscript variable for columns 
FileSpec File specification for the output disk file 
TheFile Internal file name in the subprogram 
Discussion 


Use this subprogram with Load2Arr to transfer data between arrays in memory and 
disk files. To enter the data into the array from the keyboard, use Key2Arr. If you 
hhave one-dimensional arrays, use Savefrr and LoadArr. To display the file names 
on disk before asking for the output filespec, use the ShouDir subprogram in your 
main program just before invoking Save2Arr. 
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Modifications 


None 





Name: SaveTxt 
‘Type: Procedure 
Purpose: To save a string array’s contents onto a text disk file 
Calling Sequence: SaveTxt(TextArray, LineCount, Code) 








Description 


SaveTxt prompts you for a filespec, creates a disk file with that name, and then 
saves onto that disk file the contents of the string array. The companion subpro- 
‘gram LoadTxt can later load the data back into an array. 


Input 
TextArray string Array in which data is stored 


LineCount integer Number of lines occupied in the array 


In addition, the following global const and type declarations must be specified in 
your main program. Actually, TextSize (the maximum number of text lines) and 
LineSize (the maximum length of cach line) are not required by this subprogram 
but are required by related subprograms, and these declarations are the recom- 
‘mended means of defining TextArrayType. The numbers 250 and 120 are examples, 





const 
TextSize = 250, 


type 
LineSize = stringC1203, 
TextArrayType = arrayl1, TextSize] of LineSize, 


Output 


Code integer Error code from DOS. If Code is zero, the file was 
successfully saved on disk. Positive values are the 
‘decimal equivalents of the 1/O error codes in 
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Appendix G of the Turbo manual. Negative one (-1) 


indicates that the user canceled the request to save 


the array on disk. 


SaveTxt creates an output disk file, using the filespec you enter at the keyboard 
while running the subprogram. After successfully saving the file, the subprogram 


displays a message showing how many lines were written to the text file 


Limitations and Error Conditions 


If LinaCount is less than 1, the subprogram is bypassed. If you enter a null filespec, 
Code is set to -1, and the rest of the subprogram is bypassed. If a file already exists 
with the same name you provide, the old file is replaced by the new one, If the 
file cannot be saved on disk, the subprogram beeps and displays Code with a message 
saying which 1/O statement encountered the error (reurite, write, or close). 
Code is the decimal equivalent of the hex 1/O error number listed in Appendix G 
of the Turbo manual. For example, decimal 240 is hex FO, indicating that the data 
area of the disk is full. Decimal 241 (hex F1) means that the directory is full. 


Sample Usage 
program Samp|eUsageOfSaveTxt; 


const 
TextSize = 250, 


type 
LineSize = stringC1203, 
ToxtArrayType * arrayC1.. TextSize) of LineSize, 


var 
TextArray TextArrayType; 
LineCount, Code = integer; 


(SI SaveTxt. PSL) 


BEGIN 
TextArray(i] \= “See the guick brown fox’; 
TextArrayl2] ‘= ‘jump over the lazy dog."; 
LineGount <= 2; 
SaveTxt(TextArray, LineCount, Code); 
if Code © @ then 
writeln(’ Unsuccessful file save.) 





(Hod. #1) 


(Hod. #1) 


‘TURBO PASCAL PROGRAM LIBRARY. 





This sample program produces the following output on the screen if you provide 
B:ARRAYTST.TXT as the filespec 








w= Enter filespec for text output file, or =# 
‘** press CEnter] key to cancel. - 


B:ARRAYTST.TXT 
we 2 text lines written to file B:ARRAYTST TXT 


Subprogram Listing of SaveTxt.PSL 
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Variables 
J Subscript variable 
FileSpec File specification of the output disk file 
TextFile Internal file name in the subprogram 
Discussion 


Use this subprogram with LoadTxt to transfer text data between arrays in memory 
‘and disk files. Use KeyTxt to enter the data into the array. To display the file names 
(on disk before asking for the output filespec, use the Shoullir subprogram in your 
‘main program just before invoking SaveTst. 


Modification 
Modify the values of TextSize and LineSize to match the data you are working 
with. See LoadTxt for details. 
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LoadArr 


Name: Loadérr 
Type: Procedure 
Purpose: To load an array from data saved in a disk file 
Calling Sequence: Loadfrr(Numfrray, Count, Code) 











Description 


You are prompted for a filespec, and the contents of the disk file are loaded into 
a real array, The companion subprogram SaveArr can create the disk file. 


Input 


Count integer Number of elements occupied in the array before 
loading it. Although normally zero, Count can be set 
to 50, for example, causing LoadArr to begin loading 
into the Sist element of the array. 


‘The subprogram prompts you for the input filespec. In addition, you must specify 
in your main program the following global const and type declarations. The number 
250 is an example, 








const 
frraySize + 258, 
type 
ArrayType = arrayC1, ArraySize) of real; 
Output 
NunArray real Array into which the data is loaded 
Count integer ‘The updated counter of the number of elements now 
in the array 
Code integer Error code from DOS. If Code is zero, the file was 


successfully loaded from disk. Nonzero values 
indicate unsuccessful loading, as explained in the 
Limitations and Error Conditions section, 


After successfully loading the file, the subprogram displays a message showing how 
many elements were loaded into the array 
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Limitations and Error Conditions 


The subprogram avoids run-time errors by turning off Turbo's 1/O error checking 
through the ($1-) compiler option. If an error occurs, Loadfrr displays the error 
code in decimal and passes it back to the main program, which you can design to 
abort or retry as you prefer. As in the SaveArr subprogram, the error number (if 
Positive) is the decimal equivalent of the hex I/O error number in Appendix G of 
the Turbo manual. The most likely errors will occur if you try to load a file that 
Was not created with Savefirr or equivalent logic. Negative error numbers are 
produced when the user decides to cancel the request by pressing the Enter key 
instead of entering a filespec (-1), of tries to load a disk file that has more entries 


than the array can hold (-2). 
Sample Usage 
program SampleUsageOfLoadArr; 


const 
fArraySize * 250, 


type 
ArrayType * arrayCl, ArraySizel of real; 
var 
NunArray » ArrayType; 
Count, Code, J © integer; 
($1 Loadérr, PSL 
BEGIN 
Count := @ 


Loadérr(Numrray, Count, Code); 
tf Code © @ then 
uriteln(’ Unsuccessful file load. Cor 
else 
for J := 1 to Count do 
writeln(J°4, NumarrayCJJ'14:18) 





END. 





» Code) 


m1) 
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‘This sample program produces the following output on the screen if you provide 
B:ARRAYTST.DAT as the filespec and if the file is the same one that was created 
by the sample program for Saver. 





* Enter filespec of input file, or ## 
» press [Enter] key to cancel == 
B:ARRAYTST.DAT 

#5 elanents now in array. “= 


1 
az 
3 
4 
5 


Subprogram Listing of LoadArr.PSL 
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Variables 
FileSpec Name of the file to read from disk, including drive and 
path, if necessary 
TheFile Internal file name in the subprogram 
Toottany boolean flag indicating whether too many elements for the 
array are in the disk file 
Discussion 


Use this subprogram with SaveArr to transfer data between arrays in memory and 
disk files, If you have two-dimensional arrays, use Save2Arr and Load2Arr. 


Modifications 
1. To convert this subprogram for use with integer arrays, change real to 
Integer in the indicated statements in both the subprogram and the 
sample program. 
2. To display the names of current disk files on the default disk drive 


before asking for the input filespec, insert the following statements after 
the statement indicated by (Hod. #2): 


uriteln(”** Files in the default disk/directory are’), 
ShouDir(’’, $10), 


You also need to add the global statements required by the ShouDir 
subprogram, as well as another include statement for ShouDir (that is, 
(SI ShouDir. PSL)) just before the statement already shown in the 
sample program. If you prefer, you can use ShouDir to display the 
directory from your main program instead of modifying the subprogram. 


Load2Arr 


Name: Load2Arr 
‘Type: Procedure 
Purpose: To load a two-dimensional array from data saved in a 
disk file 
Calling Sequence: Load2Arr(Nua2Array, RowCount, Code) 
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Description 


You are prompted for a filespec (disk drive, path, and file name). The contents of 
the disk file are loaded into a two-dimensional real array. The companion sub- 
program Save2Arr can create the disk file. 


Input 
RowCount int 





Number of rows occupied in the array before loading 
it. Although normally zero, RowCount can be set to 
50, for example, causing Load2Arr to begin loading 
into the Sst row of the array. 


‘The subprogram prompts you for the input filespec. In addition, you must specify 
in your main program the following global const and type declarations. The num- 
bers 2 and 100 are examples, 





const 
ColSize = 2; 
RouSize = 120; 


type 
Array2Type = arrayCi, RowSize, 1. ColSize] of real; 


Output 
Nun2Array real Array into which the data is loaded 
RowCount integer The updated counter of the number of rows now in 
the array 
Code integer Error code from DOS. If Code is zero, the file was 


successfully loaded from disk. Nonzero values 
indicate unsuccessful loading, as explained in the 
Limitations and Error Conditions section 
After successfully loading the file, the subprogram displays a message showing how 
many rows are now in the array. 


Limitations and Error Conditions 


Like LoadArr, Load2Arr displays any error code in decimal and passes it back to 
the main program, which you can design to abort or retry as you prefer. Error 
ccodes are passed in Code and are the same as those explained in LoadArr, with the 
if end-offile is reached without the last row being filled. 
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In that case, an error message is displayed, and RowWount includes the final (par- 
al) row, 


Sample Usage 
Program Samp] eUsageOfLoad2Arr; 
const 

ColSize = 2, 

RouSize = 100; 


type 
frray2Type = arrayC1, RowSize, 1, ColSize] of r 








r 
Nun2Av ray ArrayZType; 
RowCount, Code, J, K © integer; 





1 LoadZArr. PSL) 


BEGIN 
RowCount «= 8, 
Load2Arr(Nun2Array, RowCount, Cod 
if Code <> @ then 
writeln(’ Unsuccessful file load Code =“, Code) 





els 





begin 
‘uriteln(’ The contents of the file ars 
for J = 1 to Rowount do 
begin 
for K == 1 to ColSize do 
urite(Nun2ArrayCJ, KB: 1), 
writeln 
end 





end 
END. 


This sample program produces the following ourput on the screen if you provide 
B:SAVE2TST.DAT as the filespec and if the file is the same one that was created 
by the sample program for Save2Arr 
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w= Enter filespec of input file, or *= 

= press [Enter] key to cancel. = #* 
B:SAVE2TST.DAT 

#5 sets of 2 element(s) now in array. == 
The contents of the file are 





18° 20 
20° 40 
38 60 
ae 
10.8 





Subprogram Listing of Load2Arr.PSL 
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Variables 
J Subscript variable for columns 
FileSpec Name of file (including drive and path, if necessary) to 
read from disk 
TheFile Internal file name in the subprogram 
Toottany boolean flag indicating whether more rows are in the disk 
file than fit in the array 
Discussion 


Use this subprogram with Save2Arr to transfer data between two-dimensional arrays 
in memory and disk files. If you have one-dimensional arrays, use SaveArr and 
LoadArr 


Modifications 
None 


LoadTxt 





Name: Load Txt 
Type: Procedure 


To load a text (string) amy from data saved in a text 
disk file 


Calling Sequence: LoadTxt(TextArray, LineCount, Code) 











Description 
‘You are prompted for a filespec, and the contents of the disk file are loaded into 
a string array. The companion subprogram SaveTxt can create the disk file (ater 
you type it in with KeyTxt ), or you may create the file with a word processor, a 
spreadsheet, a data base manager, or the Turbo editor. 
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Input 
LineCount integer Number of lines occupied in the array before loading 
jit. Although normally zero, LineCount can be set to 
50, for example, causing LoadTxt to begin loading 


into the 51st clement of the array. 


‘The subprogram prompts you for the input filespec. In addition, you must specify 
in your main program the following global const and type declarations. The num- 
bers 250 and 120 are examples; your values may differ. TextSize is the maximum 
number of lines of text, and LingSize is the maximum length of each line, 





const 
TextSize = 250, 





type 
LingSize = stringl120), 
TextArrayType = arrayCi..TextSize] of LineSize; 
Output 


TextArray string Array into which the data is loaded 


LineCount integer The updated counter indicating the number of lines 
now in the array 


Code integer Error code from DOS. If Code is zero, the file was 
successfully loaded from disk. Nonzero values 
indicate unsuccessful loading, as explained in the 
Limitations and Error Conditions section. 


After successfully loading the file, the subprogram displays a message showing how 
‘many lines have been loaded into the array. 





tions and Error Conditions 


LineSize cannot exceed Turbo's maximum string length of 255. Disk file lines that 
exceed LineStze in length are truncated. The subprogram avoids run-time errors 
by turning off Turbo's 1/O error checking through the ($1-) compiler option. If 
an error occurs, LoadTxt displays the error code in decimal and passes it back to 
your main program, which you can design to abort or retry as you prefer, As in 
the SaveTxt subprogram, the error number (if positive) is the decimal equivalent 
of the hex 1/O error number in Appendix G of the Turbo manual. Negative error 
numbers are produced when the user decides to cancel the request by pressing 
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Enter instead of entering a filespec (-1), or tries to load a disk file that has more 
lines than the array can hold (-2). 


Sample Usage 





‘This sample program produces the following output on the screen if you provide 
B:ARRAYTST.TXT as the filespec and if the file is the same one created by the 


sample program for SaveTxt. 






w» Enter filespec of input text file, or == 
# pross CEnter] key to cancel. ” 
B:ARRAYTST.TAT 
= 2 lines now in text array. ** 

4=See the guick broun fox 

2 jump over the lazy dog. 


Subprogram Listing of LoadTxt.PSL 
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Variables 
FileSpec Name of file (including drive and path, if necessary) to 
read from disk 
TextFile Internal file name in the subprogram 
Toottany boolean flag indicating whether too many lines for the 
array are in the disk file 
Discussion 


Use this subprogram with SaveTxt to transfer data between arrays in memory and 
disk files. When the data is in memory, operate on the data with the string ma- 
nipulation subprograms in this book. 
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Modification 
Be sure to choose carefully the values that define the size of the string array! The 
appropriate statements are indicated by (Mod. #1) in the Sample Usage program. 
Remember that memory is a scarce resource, and the memory taken up by the 
array is (LineSize + 1) times TextSize. If you know that no lines in your text file 
are longer than 80 characters, for example, then by all means change LineSize to 
88. This frees up 10,000 bytes of RAM for other uses. 


~ 





Making Music and Other Sounds 





‘The IBM PC is an amazing machine, but its sound capability is not its strongest 
feature, Unfortunately, you cannot adjust the volume of the PC speaker, which is 
limited to one voice in a single timbre. Still, you can get the speaker to play different 
frequencies (notes) and create some interesting effects. 


Music is definitely possible. To paraphrase Mark Twain, “Music on the PC is better 
than it sounds.” The PlayTune subprogram uses a “tune definition language” to play 
music specified with strings. This language is patterned after that used in the PLAY 
‘command from IBM's Advanced BASIC language (BASICA). If you have BASIC pro- 
grams using PLAY, you can easily convert them to run with PlayTune. Tunes are 
specified through Turbo strings that command the speaker to play particular notes 
for certain durations. The language is fairly natural, with notes specified by their 
conventional letters, Once your tune has been created, you can save it on disk and 
recall your music for an encore. The Playinit subprogram is used to initialize 
certain global variables for use by PlayTune. 


Sound effects are possible too. SoundEf provides a “library” of nine different effects 
ranging from an alarm to a telegraph. Each sound can be modified for just the right 
effect, Beep creates repetitive beeping sounds for use as an alert, prompt, or warning, 


PlayInit 





Name: Playinit 
Type: Procedure 
: To initialize global variables for playing music with the 
PlayTune procedure 
Calling Sequence: Playlnit 
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Description 

‘This procedure initializes global variables for subsequent use by PlayTune, Once 
PlayInit is called, PlayTune can play music you create with a special tune definition 
language. This language is modeled after that used in the PLAY statement from 
BASICA. (BASICA is IBM's Advanced BASIC. See the IBM BASIC manual for an 
explanation of the PLAY statement.) Tunes are specified by string expressions con- 
sisting of special commands. Most strings that work with BASICA’s PLAY command 
work also with PlayTune. See the PlayTune documentation for the language 
definition 


Input 
‘You must make the following global var declarations in your main program: 





arrayCt, 128] of integer; 
BaseOctave, Octave, GenNoteType, Tempo, PlayFrac: byte; 


Output 


‘The global variables PitchArray, BaseOctave, Octave, GenNoteType, Tempo, and 
PlayFrac are set to default values for subsequent use by PlayTune. 


Limitations and Error Conditions 
None 
Sample Usage 
program Samp leUsageOfPlay nit, 
var 
PitchArray: arrayC1, 128] of integer, 
BaseOctave, Octave, GenNoteType, Tempo, PlayFrac’ byte, 
J. Ke integer; 


(SI PlayInit. PSLd 
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‘BEGIN 
Playlnit, 
writeln(’ Freguencies of the Natural Notes’ =42); 
writeln; 
writen’ C D E€ F G A B) 
for J == 8 to 6 do 
begin 
for K == 1 to 7 do 
write(PitchArrayCJ # 7 +K + 21:6); 
uriteln(’ Octave’ =18, J:2) 
end 








END, 


Running this test program produces the following output: 





Frequencies of the Natural Notes 


Cp ie Jk ia ih 

33 97 44 HO Z Octave 
6 73 82 87 WB 110 123 Octave t 
181 147 165 175 196 247 Octave 2 


728 
262 294 «8 349 «992 440 «494 «Octave 3 
888 988 Octave 4 
1047 1175 1319 1997 1568 1768 1976 Octave S 
2093 2249 2637 2794 3136 G52 391 Octave 6 


Normally PlayInit is used only with PlayTune. Here, however, Playlnit is used 
to produce a chart of musical frequencies These are the frequencies in Hz (cycles 
per second) for the natural notes (no sharps or flats) allowed in the tune definition 
language. Each frequency is rounded to the nearest integer. (Sec PlayTune for a 


complete description of the tune definition language.) 
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Variables 

SharpOffset Subscript difference in the PitchArray between a natural 
note and its corresponding sharp note 

NextFreg Frequency ratio between two consecutive notes in an 
‘equal-tempered scale. (See the Discussion section. ) 

RealFreg Array of the exact frequencies (real numbers) of the 
natural notes in a particular octave 

BaseFreg Frequency of the note A in the lowest octave 

BaseOctave Lowest octave allowed 

Octave ‘The relative octave used in the subsequent music. The 


actual octave is Octave + BaseOctave, 


GarNoteType Default note type. A value of 1 corresponds to a whole 
note, 2 to a half note, 4 to a quarter note, etc. 


Tempo ‘The musical tempo defined as the number of quarter notes 
in a minute 
PlayFrac Fraction of the time (in eighths) that the music plays for 


the duration of each note. A 1 means that the music plays 
the first 1/8 of the time, and a pause occurs the last 7/8 
of the time. A 6 indicates music for 6/8 and a pause for 

2/8, Normal music has PlayFrac at 7. 


Jk Loop indices 


PitchArray Array containing the frequencies of all the notes defined in 
the tune definition language 


Discussion 


‘The music language for PlayTune allows notes in 7 octaves (0 to 6), Each octave 
has a range from C to B. Middle C starts octave 3. (These settings correspond 
exactly to those of BASICA’s PLAY command.) 


‘The following is an (extremely) brief discussion of some music theory as it applies 
to PlayTune and PlayInit. A little musical knowledge is assumed although you 
don’t need to absorb this information to be able to use PlayTune successfully 


‘The most common musical tunings, such as a piano tuning, use the equal-tempered 
scale. Here, the ratio of the frequencies between any two consecutive notes 
‘cluding sharps and flats) is a constant. Each octave consists of 12 notes (C, CH, D, 
Di, E, F, Ft, G, G#, A, A®, and B), Each flat is the exact same tone as the sharp 
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of the next lower whole note. For example, B flat is the same note as A sharp, 
(Ba, C flat, E#, and F flat are undefined because the intervals between B and C, 
and between E and F, are only half notes.) 


‘The frequency of any note in one octave is half that of the same note in the next 
higher octave. Thus, the constant multiplier between consecutive notes is the 
twelfth root of 2. This explains the strange constant value for NextFreg. 


To calibrate the scale, you need to specify one frequency exactly. The usual con- 
vention is that one A note has a frequency of exactly 440 Hz. Higher A notes are 
at 880 Hz, 1760 Hz, etc. Lower A notes are at 220 Hz, 110 Hz, 55 Hz, and 27,5 
Hz, (This last value is the constant in BaseFreg.) No notes other than some A's 
have frequencies with exact integer values. Yet Turbo's sound command (and the 
PC's speaker) require tones to be played at integral frequencies. Thus, Play Init 
luses NextFreg to calculate the real-number frequencies and round them to integer 
values as appropriate. 


PitchArray stores these integer frequencies for the notes allowed in the mu: 
sic language. For ease of use by PlayTune and for programming convenience 
in Playlnit, PitchArray stores these notes according (0 a certain scheme. 
PitchArrayCt] is the A at 27.5 Hz. The first 56 values in PitchArray are the con- 
secutive natural notes ending with a B. (These values span 8 octaves.) For the 
natural notes, the music language of PlayTune uses only PitchArrayl3] through 
PitchArray(51]. These include 7 complete octaves, each ranging from © to B. 


‘The sharp of each note is contained in PitchArray, offset 60 clements from the 
corresponding natural note. For example, the sharp of the D at Pitchfrrayl4 is 
found at Pi tchArrayC64J. It follows that flats are offset 59 from their corresponding 
‘atural notes, (The “illegal” values of B# and E# result in C and F, respectively, as 
you might expect. But the “illegal” values of C flat and F flat result in © and F, 
respectively.) 











Modifications 


Each of the following modifications enables you to change a default value for one 
of the music parameters. PlayTune can later reset any of them at any time, For 
each modifiable variable, the range of legal values is shown, See PlayTune for a 
‘more complete explanation of what each of these parameters does. All parameters 
must be integers in the range indicated. 


1. BaseOetave sets the lowest octave allowed. In PlayTune any resetting of 
the octave is relative to this base octave. Usually, BaseOetave is 0. Legal 
values are 0 to 6. 


2, Octave defines the starting octave of the music. Legal values are 0 to 6. 
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3. GenNoteType indicates the type of notes to be played. Legal values are 1 
{0 64. A whole note is 1, a half note is 2, a quarter note is 4, etc. 


4, Tempo sets the speed of the music as the number of quarter notes per 
minute. Legal values are 1 to 255. The default of 120 means that each 
‘quarter note plays for one-half second. 


5. PlayFrac controls the fraction of time (in cighths) that the music plays 
for cach note. Legal values are 1 to 7. The value of 7 means that the 
music plays for the first 7/8 of the note’s allotted time and is off the last 
1/8. See also the H commands in PlayTune. 


PlayTune 
Name: PlayTune 
Type: Procedure 
Purpose: To play music, using a tune definition language 
Calling Sequence: PlayTune(TuneStr ing) 











Description 
‘The tune definition language used to specify the music corresponds (almost) exactly 
to that of the PLAY command in BASICA. (BASICA is IBM's Advanced BASIC. See 
the IBM BASIC manual for an explanation of PLAY.) Tunes are specified by string 
expressions, 25 explained in the Discussion section. Most strings that work with 
BASICA's PLAY command work also with PlayTune 





Input 


TuneString string Music specified according to the tune definition 
language. (See the Discussion section.) 


In addition, you must make in your main program the following global type and 
var declarations: 





type 
TuneType = stringl255, 


var 
PitchArray arrayC1. 128) of integer; 
BaseOctave, Octave, GenoteType, Tempo, PlayFrac’ byte; 
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Before PlayTune can be called the first time, your main program must call Play Init 
so that yalues can be set for the global variables. 


Output 


PlayTune plays music from your computer's speaker according to your command 
strings. No messages are displayed. 


Limitations and Error Conditions 


Each string passed to PlayTune is limited to a length of 253 characters. (This limit 
is necessary because two dollar-signs added to the end of your string serve as a 
terminator and 255 characters are the maximum allowable string length.) 


‘The values of the various music parameters remain intact between calls to PlayTune. 
Therefore, you can play long musical pieces through successive calls to PlayTune 
without any loss of continuity. 


‘The alphabetic commands in each string must be in uppercase. If you have strings 
defined with (some) lowercase, use the ConvUp subprogram to convert the strings 
0 uppercase. 

So that PlayTune is as short and as fast as possible, no error checking of any kind 
is done during the processing of your strings, not even range checks on the numeric 
quantities. A value outside its correct range can cause fatal errors during execution, 
Unexpected string characters are skipped. Blanks are not allowed, Between prime 
commands, blanks are simply ignored. Their effect within a command, however, 
‘can cause the music to play incorrectly. 


Even if your music string contains an error, PlayTune returns (with sound off) to 
your main program unless a fatal error occurs. No (illegal) strings should cause 
PlayTune to go into an infinite loop. 


Sample Usage 
Program Samp] eUsageOfPlayTune; 


type 
TuneTyps = string 255), 


var 
PitchArray: arrayCt. 1203 of integer, 
BaseOctave, Octave, GenNoteType, Tempo, PlayFrac> byte; 
TunePart: TuneType; 
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(SI Playinit. PSL? 
($1 PlayTune. PSL) 


‘BEGIN 


PlayTune(’ CREBL2BL404BBP4GOP4020+" >; 
PlayTune CWEBLZB AO4BBPAF+F+P403T' ), 
PlayTune(TunePart), 

PlayTune’ O4AAP4030" >, 
PlayTune(TunePart); 


PlayTune(’ O4BBPAEEGL GBPEML BILGNGHALL ZOSF 1”), 
PlayTune’ LAYNDOGFWMLLZF+HNLAEMLLZBRNLA ); 
PlayTune(’ DPSDEDY’ ) 

END. 


‘This program plays the classic melody from Tbe Beautiful Blue Danube, by Johann 
Strauss, Jr., in the key of D. 


Subprogram Listing of PlayTune.PSL 
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Variables 
Variables for the Procedure PlayTune 
SharpOffset Subscript difference in the Pitehfirray between a natural 


‘note and its corresponding sharp note 
BaseOctave Lowest octave allowed 
Octave The current octave relative to BaseDctave. That is, the 


actual octave is BasoOctave + Octave. 


GenNoteType Default note type. A value of 1 corresponds to a whole 
note, 2 to a half note, 4 to a quarter note, etc. 
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Tempo 


PlayFrac 


PitchArray 


PlayTine 
IdleTine 
DotTime 


NoteTine 


NoteType 


PitchIndex 
Position 
Number 
Character 
NextChar 
oK 


The tempo of the music defined as the number of quarter 
notes in a minute 


Fraction of the time (in eighths) that the music plays for 
each note. A 1 means that the music plays the first 1/8 of 
the time, and a pause occurs the last 7/8 of the time, A 6 
means music for 6/8 and a pause for 2/8. Normal music 

has PlayFrac at 7. 


Array containing the frequencies (to the nearest integer) 
of all the notes defined in the tune definition language 


Number of milliseconds that music is on for cach note 
‘Number of milliseconds that music is off for each note 


‘Time interval (in milliseconds) for one-half note at normal 
tempo augmented by dotted notes, if any 


Number of milliseconds for each note. NoteTine is 
PlayTine + IdleTine. 


‘Type of note to play, using the same conventions as 
GenNoteType 


Index into PitchArray for the note to be played 
Current position in TuneStr ing 

‘A number returned by Str ipNusber 

Character at TuneStringlPosition] 

Character at TuneStringCPosition +1] 


boolean return flag from StripNumber. If OK is true, a 
number was found; if OK is false, no number was found. 


Variables for the Embedded Procedure StripNuaber 


NunberLength 


CharValue 
Code 

Numb 
ByteNumb 


Length (in characters) of a substring from TuneStr ing, 
containing a numeric quantity 

‘One character from the substring 

Code passed back by val 

Integer number passed back from val 

Numb set to a byte variable 
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Discussion 
TuneStr ing consists of a scries of concatenated commands. No separator is needed 
between commands. All alphabetic commands must be in uppercase. Unless spe- 
cifically indicated otherwise, each command is exactly like the PLAY statement in 
BASICA, 


A lowercase n after a command indicates that an integer number must immediately 
follow the alphabetic character as part of the same command. 


‘The following are the primary commands for PlayTune: 





AG (with optional #, +, or - following) Plays the note indicated. The 
# or + afterward indicates a sharp, and - indicates a flat 


Lin Sets the length for all notes that follow. L1 is a whole note, and L4 is 


quarter note. That is, the actual note length is 1/n, in which the 
value of n may range from 1 to 64. L4 is the default. 


‘The length also may follow a particular note when you want to 
‘change the length of that note only. Thus, L4AB-16C indicates to play 
a quarter note A, a sixteenth note B flat, and a quarter note C. 


'F This is ignored. (It is music foreground in BASICA’s PLAY.) 
MB This is ignored. (It is music background in BASICA's PLAY.) 
HS Music staccato. Each subsequent note plays 3/4 of the time specified 


by L and is off the last 1/4 of the time. 


‘NH Music normal. Each subsequent note plays 7/8 of the time specified 
by L and is off the last 1/8 of the time. MN is the default M command, 


ML Music legato, Each subsequent note plays the full period specified by 
L (There is no delay between notes.) 


On Sets the octave for subsequent notes relative to the base octave. In 
other words, the current octave is made equal to n plus the base 
octave. The resultant octave must be from 0 to 6, Thus, there are 7 
octaves, cach with a range from C to B. Middle C begins octave 3. 
The value of n must be from 0 to 6. The default is 3. (BASICA’S 
PLAY does not contain base octaves. That is, the base octave is 
effectively 0 with PLAY.) 


Pn Pauses or rests. The value of n may be from 1 to G4. The length of 
the pause is determined by n, as for the L command. 
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Sn Sets the scale or base octave for all succeeding 0 commands. Using S 
does not change the current octave. The value of n must be from 0 
to 6. The default is 0. (This command is an addition to BASICA's 
PLAY statement.) 


Tn Adjusts the tempo for subsequent music. This command sets to n the 
number of quarter notes per minute. The value of n may range from 
32 to 255, The default is 120. A quarter note plays for one-half 
second. 


In addition, a dot (or period) after a note specification causes the note to be played 
as a dotted note. This means that its length is multiplied by 3/2. More than one 
dot may appear after each note, each dot causing another 3/2 multiplier to the 
total length. For example, L4C.. causes a C to be played 9/4 as long as a quarter 
note. Dots can appear directly after a note even if a numeric length designator 
appears (for example, 8. ). Dots may also be used after a P command to extend 
the pause length in the same manner. 


‘The X command (play substring) and n=variable commands from BASICA’s PLAY 
are not implemented in PlayTune. No semicolons (or any other separators) are 
needed between commands. Separators are simply ignored by PlayTune and have 
no effect on the resulting music. 


If your music contains repetitious phrases, sct string variables to these specific 
phrases, Then call PlayTune with the string variable name as the argument so that 
you can play these phrases whenever you like. 

If you're working from sheet music, it's usually a good idea to find the lowest note 
and define that in octave 0. Then set your other octaves higher as required. You 
can later scale everything up a few octaves with one S command at the beginning 
of your music. If you make your initial 0 commands too high, you cannot lower 
them with a call to 5; you can only raise them. 


PlayTune contains two embedded procedures. Str ipNumber removes a numeric 
‘substring from TuneStr ing. DottedNote processes dotted notes if any are present, 


Modifications 
1. You can set the tempo outside the range possible with the T command by 
adjusting the value of DotTime in the indicated line. DotTine is the number 
of milliseconds allotted to a half note at normal tempo (before any 
dotting). If you change DotTise to 259, for example, all music plays four 
times as fast as otherwise specified. DotTine must have a positive intezer 
value, 
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2. The three lines indicated by (Hod. #2) define the musical envelopes for 
‘Staccato, normal, and legato music. PlayFrac is the fraction of the time (in 
cighths) that the music plays during the time interval allowed for each 
note. In each of these three lines, PlayFrac must be set to an integer value 
from 1 to 8. You can experiment with values smaller than 6 to see the 
effect on your music. If you change normal music (the second of these 
three lines), put an early MN command in your music to override the 
default setting for normal music caused by Playnit 


SoundEff 


Name: Soundé ff 
‘Type: Procedure 


Purpose: To play various sound effects through the computer's 
speaker 


Calling Sequence: Sound€ff (Effect, RelativePitch, NumberToDo) 











Description 


‘This procedure provides nine fundamental sound effects you can use to enhance 
your programs. In addition, three frequency ranges are available for each effect. 
‘You can have any effect continuously repeated any number of times. The net result 
is a powerful sound effects generator. SoundEf f is meant for “serious” sound effects. 
For music, use PlayTune, and for simple beeping sounds, use Beep. 


Input 
Effect Scalar ‘The sound effect desired. It must be one of the 
values in the declared scalar type EffectsList. 
RelativePitch Scalar The desired frequency relative to the base 


frequency. RelativePitch must be one of the 
values in the declared scalar type PitchFreg, 
namely, LovPitch, MediunPttch, or HighPitch, 


NumberToDo integer Number of times to repeat the sound effect 


In addition, the following global type declarations must be made in your main 
Program. They define the declared scalar types EffectsList and PitchFrag. 


MAKING MUSIC AND OTHER SOUNDS 197 








type 
EffectsList = (Alar 





Bounce, Coin, Crickets, Falling, 
Siren, Telegraph, Zap, Zoom); 
PitchFreg = (LouPitch, MediuaPitch, HighPitch); 


Output 


‘The requested sound effect plays through the computer's speaker. No messages are 
displayed on the screen. 


Limitations and Error Conditions 
If Number ToDo is less than 1, the sound effect is still produced once, 


Sample Usage 
Program Samp|eUsage0fSoundEf f, 


type 
EffactsList * (Alarm, Bounce, Coin, Crickets, Falling, 
Siren, Telegraph, Zap, Zoom); 
PitchFreg = (LowPitch, MediumPitch, HighPitch), 


var 
Effect EffoctsList; 
RelativePitch  PitchFreg, 
Number ToDo integer; 


($1 SoundEff. PSL) 


BEGIN 
randomize; 
elrser; 
writeln(’ I hear the crickets at night by the pond.’ ), 
SoundEff (Crickets, MediuaPitch, 2); 
uriteln(’ I dropped @ penny on the floor." ); 
SoundEff (Coin, HighPitch, 1); 
delay(500); 
Effect = Alarm, 
RelativePitch «= MediumPitch, 
NunberToDo = 3; 
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writeln(A police car is going by.”); 

SoundEff (Effect, RelativePitch, NumberToDo); 

uriteln(My gosh, there goes a spaceship!” ), 

SoundEFT (Zoom, LowPitch, 1); 

writeln(’ I’’m sending out a telegraph message about it.” ); 
SoundEff (Telegraph, MediumPitch, 2) 


Running this test program produces the following output on the screen; 





I hear the crickets at night by the pond 

1 dropped a penny on the floor 

A police car is going by. 

sh, there goes a spaceship! 

Vm sending out a telegraph message about it. 


Of course, each of these five sound descriptions is accompanied by the appropriate 
sound effect on the speaker. 


Subprogram Listing of SoundEff.PSL 

















Variables 
NumberDone 


‘The number of times the sound effect has been repeated 
PitchFactor 


Multiplicative factor that adjusts the sound frequency and 
therefore the pitch. (See the Modifications section. ) 
JK AN Loop indices 


Discussion 


When appropriate, sound effects greatly enhance your programs. Unfortunately, the 
sound-effects capability of the IBM PC is somewhat limited, The PC's speaker's 
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volume cannot be adjusted, it is capable of only one voice, and it has just a modest 
frequency response 

Many different effects are possible, however. SoundEff contains a “library” of nine 
fundamental sounds. Each one can be altered by the Relat vePi th and NuaberToDo 
parameters. The nine sounds have identifying names: Alarm, Bounce, Coin, Crickets, 
Falling, Siren, Telegraph, Zap, and Zon. Use your imagination when you try each 
of the sound effects. Some undoubtedly will suggest other things to you. 


SoundEff contains an embedded function and two embedded procedures. 
AdjustedPitch adjusts the normal sound pitch according to the parameter 
RelativePitch. TurnOn and TurnOff tun on sound and turn off sound. Each pro- 
cedure includes a parameter for pausing for a specified period of time before re- 
turning to the calling program. 

Be sure to put a randomize statement in your main program before calling SoundEf, 
Some of the effects use the random number generator to create their sounds, 


Modifications 


1, Each sound effect has its standard (regular) frequency range. When 
RelativePitch equals MediusPitch, this regular frequency range is 
produced by SoundEff. When RelativePitch equals LouPitch or 
HighPitch, the frequency range is modified and the sound effect is 
changed somewhat, PitchFactor applies a multiplicative factor to the 
regular frequencies to accomplish these changes. By changing the 
formula in the line indicated by (Mod. #1), you can make the frequency 
range a different function of RelativePitch. PitchFactor must be a 
positive integer. 


2. For several of the nine sound effects, the function Ad justedPitch 
calculates frequency adjustments required by the particular sound effect. 
‘These frequency adjustments are expressed as a function of PitehFactor. 
(PitchFactor is calculated in the line indicated by (Mod. #19.) The 
formula for calculating Ad justedPi tch is in the line indicated by (Mod. 
#2). You may want to change the 2 at the end of the line to some other 
integer. 

3. You have unlimited possibilities in modifying the various sound effects. 
All effects include numeric constants, which can be adjusted. Experiment 
to see whether you can produce effects more to your tastes or needs, 
‘You may even add completely new effects to the case statement. If s0, 
add their names to EffectsList. 
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Beep 





Name: Beep 
‘Type: Procedure 

Purpose: To sound beeping noises from the speaker 

Calling Sequence: Beep(NumberToDo, Pitch, Duration) 











Description 


Beep creates repetitive beeping sounds. These are useful as a prompt (for expected 
input), as an error warning, or as a general alert to the user. You can specify the 
‘number of beeps to make, as well as the pitch and duration of each beep. Modifiable 
default values are maintained for each of these parameters so that Beep can be 
called with simple arguments (all zeros) to achieve a known effect. 





Input 


NumberToDo integer Number of beeps to produce. If NumberToDo is zero 
or negative, the default setting is used. 


Pitch integer The pitch (or frequency) of each beep in cycles per 
second. If Pitch is zero or negative, the default 
setting is used. (See PlayInit for the 
correspondence between different frequency values 
and the musical scale.) 


Duration integer Time duration for sounding each beep expressed in 
milliseconds. If Duration is zero or negative, the 
default setting is used. 





Output 


‘The desired beeping is produced through the computer's speaker. No messages 
are displayed on the screen. 


Limitations and Error Conditions 


Be sure that you request beeps which are audible. An extremely high pitch, say, 
Pitch > 15000, is too high for the human ear (and probably not within the speaker's 
frequency response), Many PC speakers produce a simple click if you request a 
pitch in such a high range. In addition, an extremely quick sound, such as Duration 
‘<5, cannot be accurately produced by most PC speakers. You will have to test 
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these conditions on your particular computer because speakers vary from one com- 
puter to the next. 


Sample Usage 
program Sanplelisage0fBeep; 


var 
NumberToDo, Pitch, Duration: integer; 
(SI Beep. PSL) 


‘BEGIN 
NumberToDo «= 5; 
Pitch: o= 58, 
Duration == 500; 
uriteln(’Hare are 5 low-pitched beeps, each for 1/2 second.’ ), 
Beap(NunberToDo, Pitch, Duration); 
delay (2000); 
uriteln(’Here is the default beeping‘), 
Beep (0, 2,0) 
END. 


Running this test program produces the following output on your screen: 


Hare areS low-pitched beeps, each for 1/2 second. 
Hore 1s the default beeping 


Of course, the appropriate beeping accompanies cach message as it is displayed 


‘on the screen. 


Subprogram Listing of Beep.PSL 
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Variables 
Delaylength The delay time in milliseconds between the end of one 
beep and the beginning of the next beep 


DefaultNunb Default number of beeps to produce if NunberToDo is less 
than 1 


DefaultPitch Default pitch in cycles per second. This is the pitch used 
IF Pitch is less than 1, 


Defaul tDur Default time duration in milliseconds to sound each beep, 
‘This is the duration used if Duration is less than 1. 


J Loop index 


Discussion 


‘You don't need to use Beep if you need only one beep at the computer's standard 
pitch and duration. The following Turbo statement accomplishes this; 


wri 





#7) 


Beep is useful when you want program control over the pitch and duration of each 
beep or over the number of beeps to produce. 
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Ifyou have frequent use for beeping at a particular pitch, duration, and/or repetition 
rate, you can reset the default constants DefaultPitch, DefaultDur, and/or 
Defaul tNumb, You can get any of the default values by calling Beep with a value of 
zero for the appropriate parameter. (See the Modifications section.) 


Modifications 


1, DelayLength is the pause time after cach beeping noise. If NunberToDo is 
greater than 1, DelayLength is the time interval between beeps. This 
delay is also used after the last beep before the subprogram returns. Its 
‘current setting is 200 (1/5 of a second). 


2, DefaultNunb is the number of beeps to produce if NunberToDo is zero or 
negative, If you change Defaul tNunb to zero, the subprogram is bypassed 
‘completely (no beep is produced) when NunberToDo is less than 1 


3, DefaultPitch is the pitch to use if Pitch is zero or negative. The 
current setting of 440 for DefaultPitch produces an A note. (See 
Playlnit.) 

4, DefaultDur is the time duration to sound each beep if Duration is zero 
‘or negative. The current value of 250 for Defaul tDur produces a beep 
for 1/4 second. 
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Sorting 





‘One of the great mysteries to beginning programmers is why there are so many 
different techniques to sort data into ascending (or descending ) order. Why doesn't 
someone take the time to figure out which technique is best so that everyone can 
use it? Can't we get rid of all these sorting routines with the strange names—like 
bubble sort, selection sort, insertion sort, Shell's sort, heapsort, quicksort, radix 
sort, and countless others? 


Life is not that simple, however. The truth is that virtually every sorting technique 
has some merit and is best in certain (sometimes obscure) cases. Entire books 
have been written discussing the trade-offs among various techniques and explaining 
how to sort efficiently. 


In choosing a technique, you should consider many factors. Some of these are the 
amount of data to sort, the size of the sort key, the order of the data before the 
sort, the architecture of the computer being used, the capabilities and efficiencies 
of the language in which the sort is programmed, the characteristics of peripheral 
devices that may hold portions of the data during sorting, the size of working 
memory available, and the simplicity of the algorithm, 

Included in this chapter are two sorting techniques that work well in a broad range 
of circumstances. Each sorting subprogram in our library uses one of these tech- 
niques. See the Discussion sections of SortSIR and Sor tHR for details about choosing 
between the “straight insertion” and the “heapsort” methods. The chapter contains 
eight subprograms: Sor tSIR and Sor tHR for one-dimensional real or integer arrays; 
SortSI2R and SortH2R for two-dimensional real arrays; SortSIT and SortHT for 
text (string) arrays; and SortSIRT and SortHRT for paired arrays, one real or 
integer, and the other one text. 
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Name: SortsIR 
Type: Procedure 
Purpose: To sort a real array, using the straight insertion technique 
Calling Sequence: SortSIR(NumArray, Count) 











Description 


This subprogram sorts in ascending order the elements of a one-dimensional real 
array, using the straight insertion technique. You can modify the subprogram to 
sort an integer array (SortSI1) of to sort in descending order. The sort is per- 
formed in place, meaning that no extra work storage is needed for the sort proces. 


Input 
Nunfrray real Array to be sorted 
Count integer ‘The number of array elements to be sorted 


In addition, you must specify in your main program the following global type dec- 
laration, preferably using the global const declaration shown (for compatibility with 
other subprograms). The number 250 is an example; your array size may differ. 





const 


ArraySize = 250, 


type 
ArrayType = arrayC1. ArraySize] of real; 
Output 
Nunfirray real ‘The same array, now sorted 


Limitations and Error Conditions 


IfCount is less than or equal to 1, the sort procedure is bypassed, no error message 
{s displayed, and the normal beginning and ending messages do not appear. No 
other error checking is done. Your responsibility is to make sure that Count is 
accurate and does not exceed the size of the array (ArraySize). SortSIR works 
with a minimum of two elements; the maximum number of elements is limited 


SORTING 209 





only by the data segment memory size and your patience in waiting. You may set 
Count to less than ArraySize. Only the first Count elements are sorted. 


Sample Usage 
program SampleUsage0fSor tSIR; 
const 
ArraySize = 250; 
type 
ArrayType = arrayCi..ArraySize] of real; (Mod. #1) 


var 
Numfrray © ArrayType; 
Count int 





(SI SortSIR. PSL) 


BEGIN 
Numrray£1] i= 4.2;  NusfrrayC2] <= 1. 03; 
NumfrrayC3] = -2.3, NumfirrayC4] <= 4.17, 
Gount = 4; 
SortSIR(NumArray, Count); 
welteln(NumArrayCt3:6:2, Nuwirrayl2]:6:2, NumArray(33‘6:2, 
NumArrayl4] 6:2) 





END. 


Running the test program produces the following output on the screen: 






Begin SortSIR 
4 entries sorted 
“2.38 103 417 420 
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Subprogram Listing of SortSIR.PSL 





Variables 
J Subscript variable that points to the array’s current 
clement to be inserted into the correct order 
k Subscript that points to the position below J where the 
current element is to be inserted 
ThisValue Contents of NunArrayCJ3, the current element being sorted 
Discussion 


‘This sorting technique should be familiar to many cardplayers who put their hands 
in order by working from one end to the other. Imagine that you are playing bridge. 
‘To sort your hand of 13 cards, start with the second card from the left. If it is in 
the correct order compared to the first card, leave the second card where it is, 
Otherwise, exchange it with the first card. Now look at the third card, Compare 
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it with the second and first cards and insert the third card where it belongs. If you 
continue with this procedure until you get to the 13th card, your hand will be in 
‘order. This method is called a straight insertion sort (sce Section 5.2.1 of Donald 
E, Knuth’s The Art of Computer Programming, Volume 3, Sorting and Searching) 
because a scan is made through the array, from low subscript to high, with each 
element being inserted in the correct place among the previous elements already 
sorted. 


‘To sort an integer array, refer to modification 1 in the Modifications section. To 
sort in descending order rather than ascending, see modification 4, To sort text 
(a string array), use SortSIT (sort: straight insertion, text). 


Dozens of sorting techniques are in use today, and each has its merits. The straight 
insertion technique is good choice on two occasions: when you have only a small 
number of elements to sort (say, less than 30 or 40), of when you have an array 
that is nearly in the correct order. The straight insertion technique’s other main 
advantage is that it uses minimal memory: the technique can be coded compactly 
and sorts the array in place. As the size of the array grows, however, the efficiency 
of the sort decreases rapidly if the beginning sequence is random. 


Generally, when the number of elements to be sorted doubles, the sort time qua- 
druples. This guideline applies to the actual number of elements sorted (that is, 
Count), not to the maximum size of the array specified by ArraySize, For this reason, 
you'll find the heapsort technique (SortHR for real arrays) much faster for large 
arrays in random sequence. But straight insertion is extremely efficient when your 
array is already nearly in order. Unlike many other techniques, straight insertion 
takes advantage of the previously existing sequence. Table 8.1 shows approximate 
sorting times for arrays filled with random real numbers and also for arrays with 
only one or two clements out of order. See Appendix D for details about the 
environment used for timings. 





Table 8.1 
Approximate SortSIR Timings 
Time (in Seconds) 


Count. Random Almost 
Sequence in Sequence 
25 o1 <01 
50 03 <o1 
100 10 ol 
200 40 02 
400 160 03 


800 63.0 05 
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Modifications 


1, To sort an integer array instead of a real array, change the word real 
to Integer in the global type declaration. Make the same change to the 
statement indicated by (Hod. #1) in the SortSIR Subprogram Listing 
‘These modified lines will look like this: 


type 
ArrayType = arrayCi. ArraySize] of integer; 
ThisValue * integer; 


When you save this version to your disk library, name the file SortS11. 
‘You should change the name in the procedure statement also, 

2. To eliminate checking whether Count is 2 or greater, remove the 
indicated statement. Because this change makes an insignificant 
difference in the sort’s speed, though, the change is not recommended, 

3. To eliminate displaying the messages at the beginning and end of the 
sort, delete the two indicated statements. 

4. To change the sort from ascending to descending order (that is, with 
largest numbers first), change the lessthan sign (€) to a greater-than 
sign (2) in the indicated statement. 


SortHR 





Name: Sort 
‘Type: Procedure 
Purpose: To sort a real array, using the beapsort technique 
Calling Sequence: SortHR(NunArray, Count) 














Description 


Like SortSIR, this subprogram sorts in ascending order the clements of a one- 
dimensional real array. SortHR, however, uses the heapsort technique, which is 
much faster except for very small arrays or those that are nearly in order. You can 
modify SortHR to sort an integer array (SortHI) or to sort in descending order. 
The sort is performed in place. 
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Input 
Nunrray real Array to be sorted 
Count integer The number of array clements to be sorted 


In addition, you must specify in your main program the following global type dec- 
laration, preferably using the global const declaration shown, The number 200 is 
an example. 





const 
ArraySize = 200, 


type 
ArrayType = arrayCl frraySize] of real, 
Output 
Nunrray real The same array, now sorted 


Limitations and Error Conditions 


If Count is less than or equal to 1, the sort procedure is bypassed, but no error 
message is displayed. No other error checking is done. Your responsibility is to 
make sure that Count is accurate and does not exceed the size of the array 
(ArraySize), SortR works with a minimum of two elements; the maximum num 
ber of elements is limited only by the memory size of the data segment. You may 
set Count to less than frraySize. Only the first Count elements are sorted, 


Sample Usage 
program SampleUsage0fSor tHR, 


const 
frraySize = 200; 


type 
ArrayType = arrayCl. ArraySize] of real, (od. #1 


var 
Nunfrray © ArrayType; 
Count, J © integer: 


(SI Sorte PSL) 
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BEGIN x very 
NumérrayCt] <= 47.19, 
Nundrray 





4 
for J '= 1 to Count do writeln(NumrrayCJ3:8:2) 
‘END. 


This test program produces the following output on the screen: 





The sorted data = 
12.78 


14 
21.68 
72.00 
47.19 


Subprogram Listing of SortHR.PSL 





Subscript variables used to keep track of the elements in 
Nunfrray while SortHR arranges it into a heap and then 
selects the elements in the correct order. (See the 
Discussion section. ) 

An clement of Nusfirray, now being sorted 





216 ‘TURBO PASCAL PROGRAM LIBRARY. 





Discussion 


After reading the Discussion section of SortSIR, you may identify with the bridge 
player who uses the straight inscrtion technique to arrange cards in a hand. An 
insertion sort is an intuitively appealing method. However, the same cannot be stid 
of the heapsort technique used in Sor tHR. We'll be amazed if any cardplayer in the 
world uses this method, efficient as it may be 


Because of heapsort’s complexity, the complete technique will not be described 
here. For details, see Section 5.2.3 of Knuth’s The Art of Computer Programming 
(mandatory reading for any serious student of sorting techniques), Generally, the 
heapsort process is similar to that used in a tennis tournament. Start with a group 
of, say, 32 competitors. Play 16 matches and have the winners go on to the next 
evel of the treelike structure to play again. Continue with this approach until only 
two players remain, who mect in the final round. The winner is considered the 
best player in the tournament, even though the winner played only five opponents, 
‘not all 31. 


‘The heapsort technique organizes the array elements into a “heap,” This is a carefully 
defined type of tree structure similar to the final “winner board" after a tennis 
tournament, except that the technique spells out the relative magnitudes of all 
participants by playing some extra matches you don't see in tennis tournaments, 
‘Then heapsort proceeds through the heap, selecting the elements in the desired 
order. 


‘You may notice something rare in the SortHR coding: numerous Pascal labels are 
in the subprogram (HI, #2, etc.). Shouldn't you avoid labels in order to adhere to 
good structured programming techniques? Normally, yes. In this case, we thought 
it best to adopt the labels suggested by Knuth so that you can follow his heapsort 
discussion if you want. We also retained his subscript naming, Refer to Algorithm 
H and exercise 18 in Section 5.2.3 of Knuth's book. 


Choose this heapsortbased subprogram over the straight insertion subprogram 
when conditions for the latter do not apply. That is, use SortHR when your array 
is large (more than 30 or 40 elements) and you can't depend on the array being 
nearly in order before the sort. Compare the timings in table 8.2 with those in 
table 8.1 to see why. 


Although not true for straight insertion sorting, the average time for heapsorting 
random data is virtually the same as that for heapsorting data which is nearly in 
‘order, When Count is greater than about 20, SortHR runs faster than SortSIR, but 
the difference may not be enough to compensate for the increased size of the code 
unless Count is 50 or more, depending on the situation. 


Heapsort is not the only sophisticated sorting technique that works well with large 
amounts of data. Other techniques, especially quicksort and Shell's sort, are often 
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Table 8.2 
Approximate Sor th Timings 
Time (in Seconds) 
Count Random 
Sequence 
25 o1 
50 02 
100 04 
200 08 
400 18 
800 40 
1600 87 
3200 188 





used. We chose heapsort because it is generally the most efficient technique that 
has all these attributes: it saves memory by sorting in place, it is reasonably short 
allowing you to type it in easily and save memory), and it is not subject to wide 
fluctuations in sorting time because of the initial sequence of the data or internal 
sort parameters. 


Modifications 


1, To sort an integer array instead of a real array, change the word real 
to integer in the global type declaration. Make the same change to the 
statement indicated by (Hod. #1) in the SortHR Subprogram Listing, If 
you save this version to your disk library, name the version Sor tH]. 
‘Change the name in the procedure statement also. 


2. To change the sort from ascending to descending order (that is, with 
largest numbers first), change the less-than sign (<) to a greater-than 
sign (2) in the first line indicated by (Hod. #2). Change <* to >* in the 
second indicated statement. 





SortSI2R 





Name: SortSI2R 
‘Type: Procedure 


Purpose: To sort a two-dimensional real array, using the straight 
insertion technique 


Calling Sequence: SortSI2R(NuaZArray, RowCount, SortCol) 
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Description 
SortSI2 sorts in ascending order a two-dimensional real array, just as SortSIR 
sorts a one-dimensional array. You specify which column contains the sort key. The 


sort is performed in place. A modification is included if you want to sort in de- 
scending order. 


Input 
Nun2Array real Array to be sorted 
RowCount integer The number of rows in the array to be sorted 
SortCol integer The column number of the sort key 


In addition, you must specify in your main program the following global type and 
const declarations. ColSize is the exact number of columns (the second dimen- 
sion) and is required. RowSize is the maximum number of rows (first dimension ) 
and is not required as a constant. Specifying RowSize, however, facilitates the type 
declaration and retains compatibility with other subprograms. The numbers 2 and 
100 are examples. 





const 
ColSize = 2, 
RowSize = 100, 


type 
frray2Typa = arrayCt. RowSize, 1, ColSize} of real, 


Output 
Nun2Avray real The same array, now sorted 


Limitations and Error Conditions 


If RowCount is less than or equal to 1, the sort procedure is bypassed, but no error 
message is displayed. No other error checking is done. Your responsibility is to 
make sure that RowCount and SortCol are accurate and do not exceed the bounds 
of the array. You may set RowCount to less than RouSize. Only the first RowCount 
clements are sorted 
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Sample Usage 
Program SampleUsage0fSor tS12R; 
const 

Colsize = 2; 

RouSize = 100; 


type 
Array2Type = arrayCt, RowSize, 1. ColSize) of real; 


var 
Nun2Array ArrayZType; 
RowCount, SortCol, J, K ° integer; 


(SI SortSIZR. PSL) 


BEGIN 
Num2ArrayC1,1] <= 4.4;  NumZArrayCt,23 °= 64.8; 
Num2ArrayC2, 1] <* -1.8; Num2ArrayC2, 2) == 11.2; 
NumZArrayC3,1] <= 3.7;  Nua2Array(3, 23 == 27.3; 
Num2ArrayC4,1] <= 2.3;  Num2Array(4, 2) := 88.5; 
RowCount <= 4; 
SortCol == 1; 


Sor tSI2R(Num2Array, RowCount, SortCol), 
writeln(’Here 1s the data, sorted on the first column’); 
for J i= 1 to RowCount do 
begin 
for K i= 1 to ColSize do 
wri te(Num2ArrayCJ, KI°9°2); 
uriteln 
end 
END 


This test program produces the following output: 





Here is the data, sorted on the first column 
10 11.28 
8.58 


é3e 
ESS 
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Subprogram Listing of SortSI2R.PSL 





Variables 


al Subscript variable that points to NuaZArray's current row 
to be inserted in the correct order 


K ‘Subscript that points to the position below J where the 
current row is to be inserted 


: Subscript for copying all the elements of one row into 
another 


ThisRow An array of ColSize clements that holds the row currently 
being sorted 
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Discussion 


Refer to the Discussion sections of SortSIR and SortH2R for details about how a 
straight insertion sort works and for potential uses of a subprogram that sorts two- 
dimensional arrays. 


When compared to SortSIR, SortSI2R takes about twice as long when ColSize is 
2, and 4 to 7 times as long when ColSize is 10. 


Modification 


‘To change the sort from ascending to descending order (that is, with largest num: 
bers first), change the less-than sign (<) to a greater-than sign (>) in the line 
indicated by (Hod. #1). 


SortH2R 





Name: SortH2R 
‘Type: Procedure 
Purpose: To sort a two-dimensional real array, using the beapsort 
technique 


Calling Sequence: SortH2R(Nus2Array, RowCount, SortCol) 














Description 


Sor tH2R sorts a two-dimensional real array into ascending order. You specify which 
column contains the sort key. The sort is performed in place. See the Modification 
section if you want to sort in descending order. 


Input 
NunZArray real Array to be sorted 
RowCount integer The number of rows in the array to be sorted 
SortCol integer The column number of the sort key 


In addition, you must specify in your main program the following global type and 
const declarations. ColSize is the exact number of columns (the second dimen- 
sion) and is required. RowSize is the maximum number of rows (first dimension ) 
and is not required as a constant. Specifying RowSize, however, facilitates the type 
declaration and retains compatibility with other subprograms. The numbers 2 and 
100 are examples. 
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Array2Type = arrayC1. RowSize, 1. ColSize] of real; 


Output 
Nun2Array real The same array, now sorted 


Limitations and Error Conditions 
If RowCount is less than or equal to 1, the sort procedure is bypassed, but no error 
message is displayed. No other error checking is done. Your responsibility is to 
make sure that RowCount and SortCol are accurate and do not exceed the bounds 
of the array, You may set RowCount to less than RowSize. Only the first RowCount 
elements are sorted. 


Sample Usage 
Program Samp|aUsage0fSor th2R, 





type 
Array2Type * array(t.RowSize, 1. ColSize of real, 


var 
Num2Array ArrayZType; 
RowCount, SortCol, J, K = integer; 
($1 Sorth2R PSL 


BEGIN 
NunZArrayCt, 13 <= 4.4,  Nun2Arraylt,21 := 64.0, 








NunZArrayC2, 1] == -1.8; Num2Arrayl2,2] == 11.2; 
Nun2ArrayC3,1] := 3.7; Nus2Array3,21 <= 27.3, 
Nun2Arrayl4, 11 <= 23;  Nua2ArrayC4, 21 := 8.5, 


RowCount == 4; 
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SortCol == 1; 
SortH2R(NumZArray, RowCount, Sor tCol 


ray, 
SST MTa/ Ls salle tad on te fleet cr oee 
for J =* 1 to Rowount do 
begin 
for K == 1 to ColSize do 
vurite(Nun2ArrayCJ, KI:9:2); 
uriteln 
‘end 
END. 


‘This text program produces the following output: 





Here 1s the data, sorted on the first coluan. 


“1.08 11.28 
2% 8S 
378 27.38 
44 64.00 


Subprogram Listing of SortH2R.PSL 
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Variables 
LJuR Subscript variables used in keeping track of rows in 
Nun2Array while Sorth2R arranges it into a heap and then 
selects the rows in the correct order, (See the Discussion 
section of Sor tHR ) 
a; Subscript for copying all the elements of one row into 
another 
Thi sRow ‘An array of ColSize elements that holds the row currently 
being sorted 
Discussion 


Refer to SortHR’s Discussion section for an explanation of the heapsort technique 
and its merits compared to those of other sorting methods. 


‘A-common use for SortH2R is to sort paired X-Y data into ascending order for the 
X values, after which the array is prepared for many other potential uses (binary 
searching, graphing, curve fitting, etc.). In such a case, ColSize is 2, and SortCol 
is 1, assuming that you put the X values in the first column and the Y values in 
the second column. 


When compared to SortHR, Sor tH2R takes about 30 percent longer when ColSize 
is 2, 60 percent longer when ColSize is 4, 2.5 times longer when ColSize is 10, 
and 5 times longer when ColSize is 25. 


Modification 


‘To change the sort from ascending to descending order (that is, with largest num: 
bers first), change the less-than sign (<) to a greater-than sign (>) in the first line 
indicated by (Hod. #1). In the second indicated statement, change ¢* to >* 


SortSIT 





Name: SortSIT 
Type: Procedure 
Purpose: To sort a text array, using the straight insertion technique 
Calling Sequence: SortSIT(TextArray, LineGount, Position, Width) 
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Description 


This procedure sorts in ascending order the elements in a text (string) array, 
using the straight insertion technique. You indicate the position and size of the 
sort key; it does not have to begin in the first position. Because the sort is performed 
in place, no extra work storage is needed during the sort process. The sequence 
for text is the ASCII sequence, in which uppercase text is distinguished from low- 
ercase text. All uppercase text is lower in sequence than lowercase text. You may 
Reed to use Convlp (or a similar procedure) to convert text data into uniform 
capitalization in order to get the sorting results you want 


Input 
Textfrray string Array to be sorted 
LineCount integer number of lines in the array to be sorted 
Position int Starting position of the sort key in each string 
Uidth Size of the sort key, in bytes 


In addition, you must specify in your main program the following global type dec- 
larations, preferably using the global const declaration shown, TextSize is the maxi- 
mum number of lines of text. LineSize is the maximum length of each line, The 
numbers 250 and 120 are examples. 








const 
TextSize = 250, 


type 
LineSize = stringlt2@3, 
TextArrayType = array[i..TextSize) of LineSize, 


Output 
Textfrray string ‘The same array, now sorted 


Limitations and Error Conditions 


If LineCount is less than or equal to 1, the sort procedure is bypassed, no error 
message is displayed, and the normal beginning and ending messages do not appear. 
No other error checking is done. Position must be in the range from 1 to 255. 
Otherwise, the subprogram will get run-time error 11 (hex) because of an invalid 
string index in Turbo's copy procedure. The sort key (which occupies locations 
Position through Position + Uidth - 1 of each string in the array) does not have 
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to be located either within the length of all the strings in the array, or even within 
the length of LineSize. The portion of the sort key that extends beyond cither the 
string length or LineSize is equivalent to the null string, and sorts as if that portion 
of the sort key were a low value. Only the first LineCount lines are sorted if 
LineCount is tess than the number of lines in the array 


Sample Usage 
program Samp|Usage(fSortSIT; 


const 
TextSize = 259; 


type 
LineSize = stringC1203, 
TextArrayType = arrayCi..TextSize) of LineSize; 


var 
TextArray © TextArrayType; 
LineCount, Position, Uidth, J: integer; 


($1 SortSIT. PSL) 


BEGIN 
TextArray(i] := “JOHNSON 192 LBS 73 IN; 
TextArray(2] ‘= ‘SMITH 167 LBS 78 IN; 
TextArray(3] i= “JONES © 184 LBS 68 IN’ 


LineGount == 3; 
Position == 4; 
Width = 10; 


SortSIT(TextArray, LineCount, Position, Width); 

for J := 1 to LineCount do writeln(TextArraylJ); 

Position := 11; 

Width == 3 

SortSIT(TextArray, LineCount, Position, Width); 

for J =* 1 to LineCount do writeln(TextArrayCJ]) 
END, 


‘This test program demonstrates how different sort keys cause the same array to 
be sorted into two different sequences. The first sequence results from a sort key 
of the first 10 bytes (name), and the second sequence results from a sort key of 
bytes 11 through 13 (weight), 
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Begin SortSIT 

3 lines sorted 
JOHSON 192 LBS 73 
ONES = 184 LBS 68. 
SMITH 167 LBS 78 
Bagin SortSIT 

8 lines sorted 

SMITH 167 LBS 78 IN 
WOES = 184 LBS 68 IN 
WOHNSON 192 LES 73 IN 


Subprogram Listing of SortSIT.PSL 
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Variables 
d Subscript variable that points to the array’s current line to. 
be inserted in the correct order 
K Subscript that points to the position below J where the 
current line is to be inserted 
ThisLine Contents of TextArrayfJJ, the current line being sorted 
Discussion 


Refer to SortSIR's Discussion section for an explanation of SortSIT and other 
sorting techniques; the same principles apply. Timing estimates for Sor tSIT depend 
‘on the length of the strings and the sort key. Timings increase with larger arrays 
just as SortSIR timings do. Use SortHT for faster sorting of large string arrays that 
are not already nearly in order. 


Modifications 


1. To eliminate displaying the messages at the beginning and end of the 
sort, delete the two statements indicated by (Hod. #1) 


2. To change the sort from ascending to descending order (that is, with 
Jangest values first), change the less-than sign (<) to a greater-than sign 
©) in the indicated statement. 


SortHT 





Name: SortHT 
Type: Procedure 
Purpose: To sort a text array, using the beapsort technique 
Calling Sequence: SorthT(TextArray, LineCount, Position, Width) 











Description 


This procedure sorts in ascending order the elements in a text (string) array, 
the heapsort technique. You indicate the position and size of the sort key; 
it does not have to begin in the first position. Because the sort is performed in 
place, no extra work storage is needed for the sort process. The sequence for text 
is the ASCII sequence, in which uppercase text is distinguished from lowercase 
text. All uppercase text is lower in sequence than lowercase text. You may need 
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to use Convlp (or a similar procedure) to convert text data into uniform capital- 
ization in order to get the sorting results you want. 


Input 
Textfrray string Array to be sorted 
LineCount integer The number of lines in the array to be sorted 
Position integer Starting position of the sort key in each string 
uidth integer The size of the sort key, in bytes 


In addition, you must specify in your main program the following global type dec- 
larations, preferably using the global const declaration shown. TextSize is the maxi- 
mum number of lines of text. LineSize is the maximum length of each line, The 
numbers 250 and 120 are examples; your numbers may differ. 








const 


TextSize = 250, 


type 
LinSize = stringCt203, 
TextArrayType * arrayCt, TextSize) of LineSize 


Output 


TextArray string The same array, now sorted 


Limitations and Error Conditions 

Refer to the Limitations and Error Conditions section of SortSIT. 
Sample Usage 
program SampleUsage0fSor tHT, 


const 
TextSize = 16, 


type 
LineSize = stringt 403, 
TaxtfvrayType = array(1.. TextSize] of LineSize; 
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var 
TextArray = TexthrrayType; 
LineGount, Position, Width, J: integer; 


(SI SortHT, PSL) 


BEGIN 
TextArrayCi3 
TextArrayl2I 
TextArray(3] 
LineCount *= 3; 

Position «= 1; 

Udth = 19, 

SortHT(TextArray, LineCount, Position, Width); 

uritaln(’ The data sorted by nase 1s’); 

for J ‘= 4 to LineCount do uriteln(TextArrayCJ), 

Position «= 11; 

Uldth == 3, 

SortHT(TextArray, LineCount, Position, Uidth); 

wrtteln(’ The data sorted by weight 1s’); 

for J = 4 to LineCount do uriteln(TextArrayCJ]) 
END. 


IN’ 
iN 
IN 





Bas 
bab 
Baa 


This sample program produces the sime output as that of the sumple program for 
SortSIT, except that SortHT does not display beginning and ending messages. In- 
stead, this sample program displays a message before each set of output. 





The data sorted by nane is 
JOHNSON 192 LBS. 73 IN 
ONES 184 LBS 68 IN 
SMITH 167 LBS 7@ IN 
The data sorted by walght is 
SMITH 167 LBS 78 IN 
(JONES 184 LBS 68 IN 
SOHNSON 192 LBS 73 IN 


Subprogram Listing of SortHT.PSL 
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Variables 
14UR Subscript variables used in keeping track of lines in 
TextArray while SortHT arranges it into a heap and then 
‘selects the lines in the correct order. (See the Discussion 
section of SortHR.) 
ThisLine A line of TextArray, now being sorted 
Discussion 


Refer to Sor ths Discussion section, which briefly explains the heapsort technique 
and indicates when this technique is superior to straight insertion. As with Sor tSIT, 
timing estimates for SortHT depend on the length of your strings and the sort key. 
‘Timings increase with larger arrays just as SorthR timings do. The size of the sort 
key makes a small difference in the sort time, but the lengths of the strings make 
4 big difference. For random 20-byte strings with a 10-byte sort key, sorting with 
SortHT takes about 2.5 times as long as sorting real numbers with SorthR. 


Modification 


‘To change the sort from ascending to descending order (that is, with largest 
values first), change the less-than sign (<) to a greater-than sign (>) in the first 
statement indicated by (Mod. #1). Change ¢= to > in the second statement indicated 
by (Hod, #1). 
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SortSIRT 





Name: SortSiRT 
Type: Procedure 


Purpose: To sort paired real and text arrays, using the straight 
insertion technique 


Calling Sequence: SortSIRT(Nusrray, TextArray, Count) 














Description 


‘This procedure sorts the elements in related real and text arrays into numerical 
‘order based on the real array. Two arrays that are related (that is, the value of an 
clement in one array is associated with the same numbered element in the other 
array) are often called paired arrays. An example is an array of test scores (the 
real array) and a second array that has the associated student names (the text 
array), SortSIRT can sort these two arrays so that the test score array is in ascending 
‘order and the student name array continues to match, entry for entry, the test score 
array. The Modifications section shows how to change the subprogram to sort based 
fon the text array instead. 


As with the other subprograms in the SortSIxx family, SortSIRT uses the straight 
insertion technique. Refer to Sor tSIR and Sor tHR for details about which sort to 
use in a particular situation, 


Input 
Nunfrray real The real array to be sorted 
TextArray string The associated text array 
Count Integer The number of paired elements (in the two arrays) 
to be sorted 


In addition, you must specify in your main program the following global type dec- 
larations, preferably using the global const declaration shown. ArraySize is the 
‘maximum number of elements in each array. LineSize is the maximum length of 
cach entry in the text array. The numbers 50 and 20 are examples. 
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const 
ArraySize = 5d; 

type 
LineSize + stringl281, 
TextfrrayType = 





ray. ArraySizel] of real; 


frrayType = 


Output 
Nunfrray real ‘The same real array, now sorted 
TextArray string ‘The same text array, now sorted to match Numrray 


Limitations and Error Conditions 


If Count is less than or equal to 1, the sort procedure is bypassed, but no error 
message is displayed. No other error checking is done. Only the first Count elements 
in each array are sorted if Count is less than the number of elements in the arrays. 


Sample Usage 
program SamplaUsage0fSortSIRT; 


const 
frraySize * 58; 


type 
LineSize = string 203, 
TextArrayType = arrayCt..ArraySize) of LineSize; 
frrayType = arrayC1. ArraySize] of real; 





var 
NunArray © ArrayType; 
TextArray > TextArrayType; 
Count, J + integer; 


($1 SortSIRT. PSL? 
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TextArraylt] == ‘Anderson’ ; 
TextArrayl2} == “Baker”; 

TextArray(3) °= ’ Charles’; 
TextArrayl4] Dinsdale’ 





Sor SIRT (Nunfirray, TextArray, Count) 
uriteln(’Here is the data, sorted eectesity “% 
for J == 1 to Count do 


writeln(NumfrrayCJI:B:2, ° = °, TextArrayCJ2) 


This program produces the following output: 





Here 1s the data, sorted nunerically. 
72.38 = Dinsdale 
81.20 = Baker 


Subprogram Listing of SortSIRT.PSL 
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Variables 
t) Subscript variable that points to the two arrays’ current 
‘elements to be inserted in the correct order 
K Subscript that points to the position below J where the 
current elements are to be inserted 
ThisNum Contents of Nua@rrayCJ3, the current real number being 
sorted 
ThisLine Contents of TextArrayCJ3, the current text element being 
sorted 
Discussion 


Refer to the Discussion section of SortSIR for an explanation of straight insertion 
sorting, Timing estimates for SortSIRT depend on the length of your strings and 
increase with larger arrays just as Sor tSIR timings do. Use Sor tHRT for faster sorting 
of large paired arrays that are not already nearly in order. 


Modifications 

1, If you have an integer array paired with a text array, change real to 
integer in the indicated statement. Change also real to integer in your 
global type definition. 

2. To change the sort from ascending to descending order (that is, with 
largest values first), change the less-than sign (¢) to a greater-than sign 
() in the indicated statement. 

3, Change the subprogram so that the sort key is the text array, not the 
real array, by changing the indicated statement to 

while (ThisLine ¢ TextArrayCKI) 
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Name this version SortSITR when you save it to your disk library. This 
change causes the entire text string, from first position to last, to be the 
sort key, If you like, you may combine this modification with the second 
one by using > instead of ¢ in this line. 


SortHRT 





‘Type: Procedure 


Purpose: To sort paired real and text arrays, using the beapsort 
technique 
Calling Sequence: Sor tHRT(Nuafrray, TextArray, Count) 








Description 


This procedure sorts the elements in related real and text arrays into numerical 
order based on the real array. The heapsort technique is used. See SortSIRT for 
details about paired arrays, 


Input 
Nunirray real The reall array to be sorted 
TextArray string The associated text array 
Count integer ‘The number of elements in the arrays to be sorted 


{In addition, you must specify in your main program the following global type dec- 
Jarations, preferably using the global const declaration shown. ArraySize is the 
maximum number of elements in each array. LineStze is the maximum length of 
cach entry in the text array. The numbers 100 and 20 are examples. 





const 
PrraySize = 100, 


type 
LineSize + stringt2a3, 
TextArrayType = arrayl1 ArraySize] of LineSize, 
frrayType = arrayC1..ArraySize] of real, 
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Output 
NumArray reall ‘The same real array, now sorted 


Textfrray string The same text array, now sorted to match NumArray 


Limitations and Error Conditions 


If Count is less than oF equal to 1, the sort procedure is bypassed, but no error 
message is displayed. No other error checking is done. Only the first Count clements 
in each array are sorted if Count is less than the number of clements in the arrays, 


Sample Usage 
program Samp] aUsage0fSor tHRT; 


const 
ArraySize = 100, 


type 
LineSize = string 209, 
TextArrayType * arrayCi. .ArraySizel of LineSize, 
ArrayType = array. ArraySize} of real, 








var 
Numérray © ArrayType; 
Textfrray © TextArrayType, 
Count, J: integer; 





($1 Sor tHRT, PSL) 

BEGIN 
NumfrrayC1] == 84.4; TextArrayC1] <= ‘Anderson’; 
NumArrayC2] «= 81.8; TextArray(2] «= ‘Baker’ 
Numrray£3] <= 98.7; TextArray(3] <= ‘Charles’; 
NumArrayC4] '= 72.3; TextArrayC4] «= “ Dinsdale’; 
Count == 4; 


SorthRT(NumArray, TextArray, Count); 
uriteln(’Here 1s the data, sorted numerically.’ ); 
for J := 1 to Count do 
writeln(NumArrayCJ1:8:2, “ =“, TextArrayCJI) 
END. 
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This sample program is the same one presented for SortSIRT and produces the 
same output: 





Here is the data, sorted nuserically. 
72.38 = Dinsdale 
81.00 = Baker 
84,40 = finderson 
93, 78 = Charles 


Subprogram Listing of SortHRT.PSL 





Subscript variables used to keep track of the arrays while 
Sor tHRT arranges them into the heap form and then 
extracts the data in the correct order. (See SortHR for 
details.) 


Contents of NusérrayCJ0, the current real number being 
sorted 
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ThisLine Contents of TextArrayCJ3, the current text element being 
sorted 


Discussion 
Refer to the Discussion section of Sor tHR for an explanation of the heapsort tech- 
nique. Timing estimates for SortHRT depend on the length of your strings and 
increase with larger arrays just as Sor tHR timings do, Use Sor tSIRT for faster sorting 
of small paired arrays and for large paired arrays that are nearly in order, 


Modifications 


1, Ifyou have an integer array paired with a text array, change real 10 
integer in the indicated statement. Change also real to integer in your 
global type definition. 


2, To change the sort from ascending to descending order (that is, with 
largest values first), change the less-than sign (¢) to a greater-than sign 
©) in the first of the two indicated statements. Change >= to ¢# in the 
second statement. 


3. Change the subprogram so that the sort key is the text array, not the 
real array, by changing the two indicated statements to 
HS: 1f TextArrayCJ) ¢ TextArrayCJ+1] then 
HP: If (ThisLine = TextArayC1J) 


Name this version SortHTR when you save it in your disk library. This 
change causes the entire text string, from first position to last, to be the 
sort key, If you like, you may combine this modification with 
‘modification 2 by using > instead of ¢ in the first line and >* instead of 
<= in thie second line. 








Searching 





Searching through an array to find a particular entry is a problem that comes up 
often in a wide variety of computer programs. Whether the search is for the name 
that goes with an account number or for a mathematical table lookup, nearly all 
programmers occasionally have to write programs that search. 


First, consider some introductory terminology. Think of how you look up a friend's 
phone number in a telephone directory. The friend's name is the search key’ or 
‘key. The phone book is the array or table in which you try to find a match or bit 
for your key. The entire listing for the friend (name, address, and phone number) 
is the entry ot array element. (For large data processing applications, the array is 
often an entire file on disk, and each entry is called a record. These terms are not 
‘used in this chapter.) A conventional phone book is sorted by customer name. But 
if you have only a phone number and you need to find the name that goes with 
it, the phone book is unsorted for your search key. The only way you can find a 
match for the phone number key is to do a serial search of the entire phone book, 
from beginning to end. (We recommend that you call the number and ask whose 
it is instead. ) 

Because there are nearly as many searching techniques as there are sorting tech- 
niques, once again we have tried to select the techniques that work best in a wide 
range of circumstances yet are still reasonably short and simple, The simplest tech- 
jue is a serial search through an unsorted array. SchURSer searches an unsorted 
array of real numbers (or integers with a modification), and SehUTSer searches 
an unsorted text (string) array. 


‘The array you search may already be sorted, or you may want to sort it with one 
of the subprograms in the previous chapter if you need to search the array re- 
peatedly. A sorted array can be searched more efficiently. The two subprograms 
provided for serially searching sorted arrays are SchSRSer for real arrays and 
SchSTSer for text arrays. For large arrays the binary searching technique is usually 
much faster. See SchSRBin for real arrays and SchSTBin for text arrays. 
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SchURSer 
Name: SchU/RSer 
Type: Procedure 
Purpose: To search an unsorted real array serially 
Calling Sequence: SchURSer (NumArray, Count, Key, Result) 











Description 
‘SchURSer searches a real array scrially, looking for a match for the Key value, The 
sequence of the array clements does not matter. If a match is found, the subscript 
of the matching element is returned in Result. If no match is found, Result is set 
to -1, This technique is suitable for low-volume searching (that is, searching small 
arrays frequently, oF searching larger arrays infrequently), For large arrays that re- 
quire frequent searching, it may be better to sort the array with Sor tSIR or Sor tHR 
and (0 search with SchSRSer or SchSRBin. See the Discussion section for details. 


Input 
Nunfirray real The array to be searched 
Count integer Number of elements in the array to be searched 
Key real The search key to be matched against the array 


entries 


In addition, you must specify in your main program the following global type dec- 
laration, preferably using the global const declaration shown (for compatibility with 
other subprograms), The number 250 is an example; your array size may differ. 





const 
frraySize = 250, 


type 
ArrayType = arrayCt. ArraySize] of real; 


Output 
Result integer The subscript (or index) of the array element that is 


found to match Key. If no match is found, Result is 
set to -1 
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Limitations and Error Conditions 


Only elements 1 through Count of the array are searched, even if the array has 
more elements in it. No error checking is done. Your responsibility is to make sure 
that Count is accurate and does not exceed the size of the array. 


Sample Usage 
Program Samp] eUsageOfSchURSer; 


const 
ArraySize = 250, 


type 
ArrayType = arrayC1, ArraySize) of real, (Mod, #1 


var 
Nunirray + ArrayType; 
Count, Result : integer; 
Key real; (Mode #1) 


(SI SchURSER, PSL) 


BEGIN 
for Count :* 1 to 8 do 
bagin 
‘NurArrayCCount] <= int(random*18.2) / 18.8; 
write(Count:3, “=, NumrrayCCount):3:1) 
end; 
uriteln; 
Count ‘= 
key = 85; 
SchURSer (Nunfrray, Count, Key, Result); 
if Result ¢ 6 then 
writeln(’No match found’ ) 
else 
writeln(’ Subscript match =’, Result, " Entry =", 
NumérrayCResult]:4-1) 





END. 


‘This sample program fills the first 8 elements of the array with random multiples 
of 0.1 in the range from 0 to 0.9 and displays these values on the screen, The 
program then searches for the first element containing the value 0.5. When a match 
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is found, the program displays the subscript and the contents of that array element, 
The following output shows two runs of the program. In the first run, a match was 
found. In the second run, no match was found. 





190.8 290.3 30.5 490.2 5:87 60.7 790.7 805 
Subscript match = 3 Entry = 85 





178.8 2°09 30.8 4901 5.2 60.2 7901 80.9 
No match found 


Subprogram Listing of SchURSer.PSL 





Variables 
J ‘Subscript variable used to point to the current array 
element being compared to the key 
Discussion 
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that cach clement is larger than (or equal to) the previous one; therefore, you 
don't need to examine every element except in rare cases, See SchSRSer and 
SchSRBIn if your array is already in order. 


‘The SchURSer searching technique is efficient in certain cases. SchURSer is a good 
choice when the array size is small (no more than 10 to 20 elements) and nothing 
is known about the keys to be matched. This condition is especially true for the 
“one shot” array search, when you simply need to match a key against an array 
once. Fooling around with a more complicated technique isn't necessary. The un- 
sorted serial search is certainly the simplest approach. 

SchURSer is also useful when the array size is small to medium (medium is an 
intentionally vague term here) and you know that a high percentage of the keys 
will match a small number of the array elements. Because the array clements don’t 
have to be in a certain sequence (unlike the other searching techniques in this 
book), you have the flexibility of putting the most frequently used values at the 
top of the array, where matches are found quickly. If, for example, the array values 
represent postal ZIP codes for a localized mailing list and three or four ZIP codes 
match over 95 percent of the searches, you should put those ZIP codes at the top 
Of the list. The efficiency in searching for that 95 percent compensates for the 
inefficiency with the other searches, unless the array is huge 


Even if your array is fairly small, the frequency of your searching may make another 
technique better. If your array has 50 clements and you search it only twice before 
the program ends, use whatever subprogram is easiest for you (probably this one). 
‘The slowest of the techniques only takes about 1/100 of a second. But if your 
program needs to search the array 1,000 times or 100,000 times, you are probably 
better off if you sort the array and use SchSRBin or SchSRSer. Look at the sort and 
search timings to be sure. 


‘The conclusion you should draw from this discussion is that you must know the 
characteristics of your data in order to choose the best searching method, Our 
intent here is to provide cnough information about the subprograms in this book 
so that you can choose wisely. Sometimes your choice may be obvious; at other 
times, you may need to study your data and make some calculations, 





‘Table 9.1 shows approximate searching times when SchURSer is used on arrays of 
different sizes. The worst-case time refers to the amount of time the search takes 
when Key does not match any array element. The average-case time refers to the 
search time for half the array. As mentioned earlier, you may greatly improve this 
average time by “stacking” the most frequently used search keys in the first few 
array elements. The timings are basically linear. In other words, if you have to search. 
through only 1/10 of the array before finding a match, the time to do so is about 
1/10 the time for the worst case. On the other hand, if many searches result in 
no matches at all, your average time will be much closer to the worst-case time. 
See Appendix D for details about the environment used for timings. 
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Table 9.1 
Approximate SchURSer Timings 


Time (in Seconds) 


Count Worst Case Average Case 
10 0.002 0.001 
25 0.006 0.003 
50 0012 0.006 

100 0.02 001 
200 005 0.02 
400 0.09 0.05 
‘800 0.18 0.09 

1600 037 0.18 

3200 073 037 

6400 146 07: 








Modification 


To search an integer array instead of a real array, change real to integer in the 
indicated line. Make the same change in the two indicated lines in the Sample Usage 
Program (or your own program). When saving this integer version to your disk 
library, name the version SehUISer. Change the name in the procedure statement 
also, Note that the Sample Usage program is not designed to work with integers, 


SchSRSer 
Name: ScbSRSer 
‘Type: Procedure 
Purpose: To search a sorted real array serially 
Calling Sequence: SchSRSer(Nusfrray, Count, Key, Result) 











Description 
SchSRSer searches a previously sorted real array serially, looking for a match for 
the Key value. Ifa match is found, the subscript of the matching element is returned 


in Result. Ifno match is found, Result is set to-1. Because the array is in ascending 
‘order, the no-match condition occurs as soon as an array element is found that ie 
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larger than the search key. This technique is suitable for low-volume searching 
(that is, searching small arrays frequently, or searching larger arrays infrequently). 
For higher-volume searching, use the SchSRBin subprogram. 


Input 
NuoArray real The array to be searched 
Count integer Number of elements in the array to be searched 
Key real The search key to be matched against the array 


entries 


In addition, you must specify in your main program the following global type dec- 
laration, preferably using the global const declaration shown (for compatibility with 
other subprograms). The number 250 is an example; your array size may differ. 





const 
ArraySize = 250; 


type 
frrayType * arrayCt. ArraySize] of real, 
Output 
Result integer The subscript (or index) of the array element that is 
found to match Key. If no match is found, Result is 
set toh 


Limitations and Error Conditions 


‘The array must be sorted into ascending order before you call SchSRSer, or incorrect 
Processing may take place. (The first array element that exceeds Key causes 
SchSRSer to end without a match; such a condition can occur erroneously if the 
array is out of sequence.) Only elements | through Count of the array are searched, 
even if the array has more elements in it. No error checking is done. Your re 
sponsibility is to make sure that Count is accurate and does not exceed the size 
of the array. 
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Sample Usage 
program SampleUsageOfSchSRSer; 


const 
ArraySize = 250, 








type 

ArrayType = array . ArraySizel of rea! (od. #1) 
var 

Numérray ArrayType; 

Count, Result : integer; 

Key real; (od. #1) 
‘$1 SchSRSer, PSL) 
BEGIN 


for Count ‘= 1 to 20 do 
Nunfirray€Count3 ‘= Count * Count, 
Count = 28, 
Koy = 100.8, 
SchSRSer (Numfrray, Count, Key, Result); 
if Result ¢ @ then 
uriteln(’No match found’ ) 
else 
uriteln(’ Subscript match =“, Result, ’ Entry =”, 
NunfirrayCResult2) 


‘This sample program fills the first 20 entries of the array with the squares of the 
‘numbers from 1 to 20 (that is, 1, 4,9, 16, 25, ..., 400). Then the program searches 
for the element that contains the value 100.0. When a match is found, the program 
displays the subscript and the contents of that array clement: 


Subscript match = 18 Entry = 1 2ag@nOnOMOE+a2 
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Subprogram Listing of SchSRSer.PSL 





Variables 


J Subscript variable that points to the array element being 
‘compared to the key 


Discussion 


See the Discussion section of SchURSer for an explanation of different searching 
techniques and suggestions about which technique to use. To search an integer 
array instead of a real array, or to search an array already sorted in descending 
order, see the Modifications section. 

‘Table 9.2 shows approximate searching times when SchSRSer is used on arrays of 
different sizes. The worst-case time refers to the amount of time the search takes 
when Key is greater than or equal to the contents of the largest array element. The 
average-case time refers to the search time for half the array. For random data, this 
search technique takes the average-case time when no match is found (unlike 
SchURSer, which takes the worst-case time), Note that the average time rarely occurs 
in real-life situations; the real average time is usually different because the data in 
‘any practical application is seldom truly random. As with SchURSer, this subprogram 
yields quite linear timings—if you search only 1/10 of the array, then the time is 
about 1/10 the worst-case time. 
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Table 9.2 
Approximate SchSRSer Timings 
‘Time (in Seconds) 
Count: Worst Case Average Case 
10 0.002 0,001 
25 0.006 0.003, 
50 oo12 0.006 
100 0.02 ooL 
200 0.05 0.02 
400 0.09 0.05, 
800 0.18 0.09 
1600 037 018 
3200 0.73 037 
6400 146 0.73 





Note that these times are the same as those shown for SchURSer. ‘The difference 
is that this subprogram does not necessarily get its worst-case time when no match 
is found, but SchURS@r docs. With SchURSer, however, you may be able to place 
the most frequently matched elements near the top of the array (greatly reducing 
the search time) because sequential order is not necessary. 


Modifications 


1, To search an integer array instead of a real array, change real to 
Intager in the indicated subprogram line. Make the same change in the 
‘two indicated lines in the Sample Usage program (or your own 
Program). When saving this integer version to your disk library, name 
the version SchSISer. Change the name in the procedure statement also. 


2. To change the subprogram so that it searches a descending array instead 
of an ascending one, change >= to < in the indicated line. 





SchSRBin 
Name: SchSRBin 
‘Type: Procedure 


Purpose: To search a sorted real array, using a binary search 
Calling Sequence: SchSRBin(NusArray, Count, Key, Result) 











SEARCHING 253, 





Description 


SchSRBin searches a previously sorted reall array, using a binary search. If a match 
is found, the subscript of the matching element is returned in Result. If no match 
is found, Result is set to -1. On randomly distributed data, the binary searching 
technique is much faster than serial techniques unless your array is extremely small. 





Input 
Nusfrray real The array to be searched 
Count integer Number of clements in the array to be searched 
Ki real The search key to be matched against the array 





entries 
In addition, you must specify in your main program the following global type dec- 
laration, preferably using the global const declaration shown (for compatibility with 
other subprograms), The number 250 is an example; your array size may differ, 





const 
ArraySize = 250, 


type 
ArrayType = array(i.ArraySize) of real; 
Output 
Result integer The subscript (or index) of the array element that is 
found to match Kay. If no match is found, Result is 
set 0-1 


Limitations and Error Conditions 


‘The array must be sorted in ascending order before you call SchSRBin, or incorre: 

processing may take place. Only elements 1 through Count of the array are searched, 
even if the array has more elements in it. No error checking is done, Your re- 
sponsibility is to make sure that Count is accurate and docs not exceed the size 


of the array. 


254 ‘TURBO PASCAL PROGRAM LIBRARY 








Sample Usage 
Program SampleUsage0fSchSRBin; 
const 
ArraySize = 250; 
type 
ArrayType = arrayCt.ArraySizel of real (Hod, #1) 
var 
NumArray ArrayType; 
Count, Result © integer, 
Key real; (Mod, #1) 


($1 SchSRBin. PSL) 


BEGIN 
for Count ‘= 1 to 21 do 
NunfirrayCount3 ‘= Count * Count; 
Count <= 21; 
Kay 81.0, 
‘SchSRBin(NumArray, Count, Key, Result); 
if Result ¢ 8 then 
writeln(’No match found’ ) 
else 
writeln(’ Subscript match =", Result, “Entry =, 
NunArrayCResult) 





This sample program fills the first 21 entries of the array with the squares of the 

‘numbers from 1 to 21 (that is, 1, 4, 9, 16, 25, .. . 441). Then the program searches 

for the element that contains the value 81.0. When a match is found, the program 
lisplays the subscript and the contents of that array element: 


Subscript match = 9 Entry = 8. 192aq@Q0QNE+01 
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Subprogram Listing of SchSRBin.PSL 





Variables 
Low ‘The subscript of the lowest element with which the 
search key can be matched 
High “The subscript of the highest element with which the 
search key can be matched 
J Subscript variable that points to the array clement being, 
compared to the key 
Discussion 


‘The binary searching technique begins by examining the middle clement of the 
‘array. If that element is larger than Key, everything above the midpoint is larger 
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also, and only the elements below the midpoint need to be considered farther. 
‘The next element considered is the one at the midpoint of the remaining elements, 
‘The binary search continues this way, eliminating half the remaining elements from 
consideration with each pass, until cither a match is found or no possible matches 
remain. This approach results in many fewer comparisons than for serial searching, 
techniques, 

For randomly distributed data, SehSRBin is faster than SchURSer or SchSRSer in 
‘worst-case situations for arrays that are larger than approximately 8 clements. For 
the average case, the cutoff is about 15 elements. As the size of the array increases, 
the binary search becomes comparatively faster. Remember, however, that the two 
serial searching techniques can yield much better than average-case results, de- 
pending on the data. The results of the binary searching technique are seldom 
better than the average-case results. (The Discussion section of SchURSer has an 
explanation of different searching techniques and suggestions about which tech. 
nique to use in a particular situation. ) 


‘Table 9.3 shows approximate searching times when SchSRBin is used on arrays of 
various sizes, The worst-case time refers to the amount of time the search takes 
when Key has no match in the array. The average-case time refers to the time 
Fequired for finding a match in randomly distributed data. From these timings, you 
can obviously see that the binary search is by far the fastest of the three techniques 
in Worst-case situations (about 10 times as fast for 200 elements, and 100 times 
as fast for 3,200 elements ) Use the binary search unless you are searching extremely 
small arrays, or unless the other two techniques are close to best-case timings 
because of frequently found matches at the top of the array. 





Table 9.3 
Approximate SchSRBin Timings 


‘Time (in Seconds) 


Count Worst Case Average Case 
10 0.002 0.002 
25 0.003 0.002 
50 0.003 0.003 
100 0.004 0.003 
200 0.004 0.004 
400 0.005 0.004 
800 0.005 0.005 
1600 0.006 0.005 
3200 0.006 0.006 


6400 0.007 0.006 
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Modification 


To search an integer array instead of a reall array, change real to integer in the 
line indicated by (Mod. #1). Make the same change in the two indicated lines in 
the Sample Usage program (or your own program). When saving this integer 
version to your disk library, name the version SchSIBin. Change the name in the 
procedure statement also. 





SchUTSer 
Name: SchUTSer 
Type: Procedure 
Purpose: To search an unsorted text (string) array serially 


Calling Sequence: SchUTSer(TextArray, LineCount, Position, TextKey, 
Result) 








Description 


SchUTSer searches a text array serially. The array doesn't need to be sorted. If a 
match is found, the subscript of the matching element is returned in Result, If no 
match is found, Result is set to -1. Ifthe text array is small and sorted, see SchSTSer. 
For high-volume searching, see SchSTBin. 


Input 
Textfrray string ‘The array to be searched 
LineCount integer Number of text lines in the array to be searched 


Position integer The starting position of the search key in each text 
line 


TextKey string The search key to be matched against the text array 
entries 


In addition, you must specify in your main program the following global type dec- 
larations, preferably using the global const declaration shown (for compatibility 
with other subprograms). TextSize is the maximum number of lines of text in the 
array, LineStize is the maximum length of cach line. TextArrayType and Str ing255 
are required by the subprogram. The numbers 100 and 25 are examples; your array 
size may differ 
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const 
TextSize = 100, 
type 
LineSize = stringtZ5J, 
TextArrayType = arrayCt.. TextSize] of LineSize; 
String255 = stringl255), 





Output 


Result integer The subscript (or index) of the array element that is 
found to match TextKey. If no match is found, 
Rasult is set to -1 


Limitations and Error Conditions 


If TextKey is a null string, no match is returned. Only elements 1 through LineCount 
of the array are searched, even if the array has more elements in it. No error checking 
is done. Your responsibility is to make sure that LineCount is accurate and does 
hot exceed the size of the array 


Sample Usage 
program Samp] eUsageOfSchUTSer; 


const 
TextSize = 109, 


type 
LineSize = stringt253, 
TextArrayType = arrayC1. TextSize] of LineSize, 
String2S5 = stringl2553, 





var 
LineGount, Position, Result = integer, 
TextArray TextArrayType, 
TextKey String2s5, 


(SI SchUTSer. PSLD 
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Textkey 
SchUTSer(TextArray, LineCount, Position, Textkey, Result); 
1f Result ¢ 6 then 
turiteln(’No match found’ ) 
else 
uriteln(’ Subscript match =’, Result, ‘ Entry =, 
TextfvrayCResult) 


‘This sample program demonstrates how SchUTSer can perform a table lookup that 
converts a two-character postal abbreviation into the state’s name. Only the first 
five states are included in this sample. The key is the state abbreviation, which 
starts in the first position of each text array element. Note that the state abbre- 
Viations are not sorted. This example is based on the assumptions that CA is the 
TextKey most often encountered and that AZ is the next most frequent key. These 
two states are therefore placed in the first two array positions to speed the search. 
(See the Discussion section.) After a match is found, the main program can use 
‘Turbo's copy function to extract the state’s name, which starts in the fourth position 
of each array element. Output from the sample program is the following: 


Subscript match = 2 Entry = AZArizona 


Subprogram Listing of SchUTSer.PSL 
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Variables 
J ‘Subscript variable that points to the array element being 
compared to the key 
Utdth ‘The size (length) of the search key passed to the 
subprogram 
Discussion 


The trade-offs among various searching techniques are covered in the Discussion 
sections of the first three subprograms in this chapter. 


‘SchUTSer performs a serial search of an unsorted array and is therefore a twin of 
‘SchURSer. SchUTSer is best for one-shot searches for which sorting the array before 
searching is not worth the time and effort, for searches of extremely small arrays, 
Or for searches of larger arrays when you expect nearly all searches to find a match 
in the first few array entries. 


Use the timing tables for the first three subprograms in this chapter as guidelines 
for the timings of the last three subprograms. Timings are less predictable for string 
arrays than for real arrays because both the string lengths and the key lengths may 
vary widely. However, the timings for these string techniques relate to each other 
the same way the corresponding real number timings do. 


Modifications 
None 
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SchsTSer 


Name: ScbSTSer 
Type: Procedure 
Purpose: To search a sorted text (string) amay serially 


Calling Sequence: SchSTSer(TextArray, LineCount, Position, TextKey, 
Result) 














Description 


SchSTSer searches a previously sorted text array serially. If a match is found, the 
subscript of the matching element is returned in Result. If no match is found, 
Rasult is set to -1. For high-volume searching, see the SchSTBin subprogram. 


Input 
TextArray string The array to be searched 
LineCount integer Number of text lines in the array to be searched 
Position integer The starting position of the search key in cach text 
line 
TextKey string The search key that is to be matched against the text 
array entries 
In addition, you must specify in your main program the following global type dec- 
larations, preferably using the global const declaration shown (for compatibility 
with other subprograms). TextSize is the maximum number of lines of text in the 
array, LineSize is the maximum length of each line. Text@rrayType and Str ing255 
are required by the subprogram. The numbers 100 and 25 are examples; the size 
of your array may differ. 





const 
TextSize = 100, 


type 
LineSize = string(253, 
TextArrayType = arrayC1..TextSizel of LineSize; 
String2S5 = stringt 2353, 
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Output 


Result integer The subscript (or index) of the array element that is 
found to match TextKey. If no match is found, 
Result is set to -1. 


Limitations and Error Conditions 


The array must be sorted in ascending order before you call SchSTSer (using as 
the sort key the same portion of cach text line that is used as the search key). If 
TextKay is a null string, no match is returned. Only elements 1 through LineGount 
Of the array are searched, even if the array has more elements in it. No error checking 
is done. Your responsibility is to make sure that LineCount is accurate and does 
not exceed the size of the array 


Sample Usage 
Program Samp] @UsageOfSchSTSer, 


const 
TextSize + 108; 


‘type 
LineSize = stringl253, 
TextArrayType = arrayCt..TextSize) of LineSize, 
String255 = stringt255, 


var 
LineGount, Position, Result © integer; 
TextArray TextArrayType; 
Textkey StringZ55, 


(SI SchSTSer. PSL2 





BEGIN 
TaxtArraylt] = 
TextArray(2] == “AK Alaska’; 
TextArray(3] ©= ‘AZ Arizona’; 
TextArrayl4] == ‘AR Arkansas’, 
Textfrray(5] «= “CA California’, 
LineCount «= 5; 


Position == 4, 





TextKey = ‘Arkansas’; 
SxhsTSer(Terthrray, LineCount, Position, Testkay, Result); 
1f Result < @ then 
uriteln(’No match found’) 
else 
uriteln(’ Subscript match =’, Result, * Entry =", 
TextArrayCResult]) 
ND. 


‘This sample program demonstrates the use of SchSTSer to perform a table lookup 
for converting a state name into a two-character postal abbreviation. (The SchUTSar 
sample converts in the opposite direction.) Only the first five states are included 
jin this sample. The key is the state name, which starts in the fourth position of 
‘each text array element. Note that the array entries are in ascending alphabetical 
‘order depending on the state name (the search key in this example), not the 
abbreviation. After a match is found, the main program can use Turbo's copy fune- 
tion to extract the state abbreviation from the first two positions of the array ele- 
ment. The sample program's output is the following: 


Subscript match = 4 Entry = ARArkansas 


Subprogram Listing of SchSTSer.PSL 
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Variables 
a Subscript variable that points to the array clement being 
‘compared to the key 
Uidth ‘The size of the search key passed to the subprogram 
Discussion 


‘The trade-offs among various searching techniques are covered in the Discussion 
sections of the first three subprograms in this chapter. Because SchSTSer performs 
4 serial search of a sorted array, SchSTSer is a twin of SchSRSer. Generally, the 
serial search of a sorted array is best for searching extremely small arrays (no more 
than 10 to 20 entries), 


‘As mentioned in the Discussion section of SchUTSer, timings of string searches vary 
widely depending on the sizes of your strings and the sort key, For guidelines to 
the relative merits of each technique in different situations, you can use the timing 
tables of subprograms that search real arrays. 


Modifications 


None 





SchSTBin 


Name: SchSTBin 
‘Type: Procedure 


Purpose: To search a sorted text (string) array, using a binary 
search 


Calling Sequence: SchSTBin(Text@rr 
Result) 








, LineCount, Position, TextKey, 








Description 


SchSTBin searches a previously sorted text array, using a binary search. If a match 
for TextKey is found, the subscript of the matching clement is returned in Result 
If no match is found, Result is set to -1. On randomly distributed data, the binary 
searching technique is much faster than serial techniques unless the arrays are 
‘extremely small 
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Input 
TextArray string The array to be searched 
LineCount integer Number of text lines in the array to be searched 
Position integer as starting position of the search key in cach text 


TextKey string The search key to be matched against the text array 
entries 


In addition, you must specify in your main program the following global type dec- 
larations, preferably using the global const declaration shown (for compatibility 
with other subprograms). TextSize is the maximum number of lines of text in the 
array, and LingSize is the maximum length of each line. TextArrayType and 
‘String255 are required by the subprogram. The numbers 100 and 25 are examples; 
the size of your array may differ. 





const 
TextSize 





100, 
type 
LineSize = stringl253, 
TextfrrayType = arrayCt..TextSize) of LineSize; 
String255 = string 2553, 


Output 
Result integer The subscript (or index) of the array element that is 
found to match TextKey. If no match is found, 
Result is set to «1. 


Limitations and Error Conditions 


The array must be sorted in ascending order before you call SchSTBin (using as 
the sort key the same portion of cach text line that is used as the search key), If 
TextKey is a null string, no match is returned. Only elements 1 through LineCount 
of the array are searched, even if the array has more elements in it. No error checking 
is done. Your responsibility is to make sure that LineCount is accurate and does 
not exceed the size of the array. 
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Sample Usage 
program SampleUsageOfSchSTBin; 


const 
TextSize = 100, 


type 
LineSize = string(252, 
TextArrayType = arrayCt..TextSize) of LinsSize; 
String255 = stringl255), 





var 
LineCount, Position, Result = integer, 
Textfrray TextArrayType; 
TextKey String255, 


($1 SchSTBin PSL) 








BEGIN 
ToxtArrayCt] °* “AL Alabana 
TextArrayl2] °* “AK Alaska’ 
TextArrayC@) <= “AZ Arizona’; 
TartArrayl4] °* “AR Arkansas’, 
TextArray(S] ‘= ‘CA Cal fornia’; 
LineCount := 5, 

Position = 4; 
TextKey Alaska’, 


SonSTBin(TextArray, LineCount, Position, TextKey, Result); 
If Result ¢ @ then 
writeln(’No match found’ ) 
else 
writeln(’ Subscript match = 
TextfrrayCResult)) 





» Result,” Entry =, 
exo 


‘This sample program, like the one for SchSTSer, demonstrates the use of a table 
lookup for converting a state name into a two-character postal abbreviation. (The 
SchUTSer sample converts in the opposite direction.) Only the first five states are 
included in this sample. The key is the state name, which starts in the fourth position 
of cach text array clement. Note that the array entries are in ascending alphabetical 
order depending on the state name (the search key in this example), not the 
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abbreviation. The sample program searches for a match for Alaska and then displays 
the entry found: 


Subscript match = 2 Entry = AK Alaska 


Subprogram Listing of SchSTBin.PSL 





Variables 
Low ‘The subscript of the lowest entry with which a match is 
possible 
High ‘The subscript of the highest entry with which a match is 
possible 
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J Subscript variable that points to the array element being 
compared to the key 
Width The size of the search key 
Discussion 


‘The trade-offs among various searching techniques are covered in the Discussion 
sections of the first three subprograms in this chapter. SchSTBin, which performs 
a binary search of a sorted array, is a twin of SchSRBin. With random data in which 
a match is always found, a binary search is faster than a serial search if the array 
size has more than approximately 15 elements. For worst-case searches, the binary 
search is faster whenever the array contains more than about 8 elements, 


As mentioned in the Discussion section of SchUTSer,, timings vary widely for string 
searching with different string and sort key sizes. For guidelines to the relative 
merits of each technique in different situations, you can use the timing tables for 
subprograms that search real arrays. 


Modifications 


None 


10 





Parsing 





Parsing is the dissection of text strings into meaningful components. Typically, 
strings are searched for certain keywords or characters that have meaning in the 
current semantic context. The Turbo Pascal compiler includes a sophisticated 
parser that must interpret Pascal program syntax so that the compiler can generate 
appropriate machine code. 


‘We use the term parsing to include what is generally referred to as lexical scanning, 
‘This is the process of searching through a string in order to construct its overall 
meaning, Individual components are interpreted one at a time for their meanings 
within the legal syntax. This is often done in “parsers” that process English com: 
mands. An adventure game is a good example of a program that includes a parser 
to process commands in English. 


Parsers generally work in one of two ways. The first is to divide the source string, 
into substrings at appropriate keywords. The substrings are then processed for 
further interpretation. The second method is to keep a pointer in the source string. 
‘A keyword check is performed at the pointer. When a keyword is found, its meaning 
is interpreted, and the pointer is updated. 

‘This chapter provides six fundamental parsing subprograms. Sp11tD searches a string 
for a specific delimiter (of any length) and divides the string at the delimiter (if 
the delimiter is found). Spl tCh searches a string for the occurrence of any single 
character delimiter from a set of delimiters you specify. Again, the string is split 
at a delimiter if one is found. SubStrD finds a substring bounded by two specified 
delimiters, 

‘The remaining three subprograms are of the “pointer” type. Given an array of key: 
words, ParseKU detects whether the pointer is at one of the keywords. ParseRN 
detects whether the pointer points to a real number. And ParseIN checks for an 
integer number. Each of these subprograms “reports” what it finds and updates the 
pointer appropriately. 

Capitalization is sometimes a stumbling block in the parsing process, Suppose that 
you have begin as a keyword. You want the parser to detect BEGIN, Begin, or even 
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BeGiN as valid. This problem is casily solved with ConvUp or ConuLow from Chapter 
11. These two subprograms convert a string to all uppercase or lowercase letters. 
If you process cach source string through ConvUp, for example, your keyword list 
for parsing needs to include only BEGIN for detecting any of the variants, 


A minor inconvenience is associated with Turbo Pascal subprograms that pass 
strings as var parameters to and from main programs, Pascal demands strict type 
checking. In other words, the string type of the actual parameter in the main pro- 
gram must exactly match the formal parameter in the subprogram. We would like 
to design the subprograms as “black boxes” that require no internal coding changes 
for adoption by any particular main program. In an ideal world, you could then 
declare strings to be whatever type you wanted and still use any of the subprograms 
without modification. 


Pascal is not this forgiving, however. (There is good reason, of course. The re- 
strictions protect you from potentially referencing beyond the active string length. ) 
A compromise is therefore necessary. Three primary “solutions” to this dilemma 
are possible, 


‘The solution in our subprograms is to declare the string type globally in the main 
Program, using the name expected by the subprogram. This solution always works 
and puts minimal demand on memory resources. The disadvantage is that each 
string in the main program must be declared with the correct type name (or one 
that matches the correct name in length), 


A second solution is to use Turbo's ($U-) compiler directive, which permits the 
relaxation of strict type checking, You place the ($0-) directive in your main pro- 
‘gram before one of the subprograms is invoked. (You can restore the type checking. 
with ($U+) right after the subprogram call.) This method permits you to declare 
variable strings of any type you want. The disadvantages are minor: you still need 
4 global declaration for each string type that occurs in the subprogram, you may 
clobber good data with mismatched string references, and this compiler directive 
‘may work differently in future Turbo releases. Because we would like this hook to 
ersevere, it's the last concern that worries us. 


‘The last solution isto use in your main programs work strings as temporary holding 
places for communication with the subprograms. You must declare an extea string 
‘type globally. A convenient choice is 


String255 = string 2553 


This declares a maximum-length string You must globally equate to Str ing255 the 
string type names used in the subprograms. You must also define some work strings 
in your main program to be this type. These work strings serve as buffers between 
the subprogrim and the active data strings in your main program, The active strings 
can be of any string type. When you want to pass one of these strings to a sub 
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program, you first equate one of the work strings to the active string. You can then 
pass the work string to the subprogram, because the work string is of the correct 
type. Similarly, you use other work strings to receive strings back from the sub- 
program. You then equate your active string variables to the appropriate work 
strings. Two disadvantages of this approach are the extra coding required and the 
extra memory needed. 





SplitD 





Name: SplitD 
Type: Procedure 
Purpose: To divide a string at a specified delimiter 


Calling Sequence: Spl {tD(SourceStr, Delimiter, LeftPart, RightPart, 
Found) 











Description 


Spl tD provides a fundamental parsing capability for processing text strings, Sp11tD 
searches source string left to right for the first occurrence of a given delimiter, 
If the delimiter is found, the source string is split into two output strings—the part 
to the left of the delimiter and the part to the right. The delimiter can be any 
length. 


Input 


SourceStr string The source string. It can be any length and may be 
specified as a variable or a literal in the calling 
statement. SoureeStr's type must be declared globally 
as ParseType 


Delimiter string The delimiter. It can be any length and may be 
specified as a variable or a literal in the calling 
statement. Delimiter’s type must be declared globally 
as DeliaType. 


‘The two string types, ParseType and Del imType, must be declared globally in the 
‘type block of the main program: 
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type 
Parselype = stringC255]; 
DelinType = stringl203; 


The lengths of 255 and 20 are examples; your maximum string lengths may differ. 


Output 
LeftPart string The substring from SourceStr to the left of 
Delimiter. LeftPart is set to the null string if 
Del tmiter is not found in SourceStr. LeftPart is of 
type ParseType 


RightPart string ‘The substring from SourceStr to the right of 
Delimiter. RightPart is set to the null string if 
Delimiter is not found in SourceStr, RightPart is of 
type ParseType 

Found boolean A flag that indicates whether Delimiter is found in 
SourceStr. If so, Found is true. If not, Found is false, 


Limitations and Error Conditions 


Wfeither Sour caStr or Delimiter (or both) is a null string, LeftPart and RightPart 
are null strings, and Found is false. 


If the delimiter occurs more than once inside the source string, only the first 
(leftmost) occurrence is processed by Sp11tD. When the delimiter occurs at one 
end of the source string, LeftPart or RightPart (as appropriate) is null. If 
Delimiter and SourceStr are identical, Found is true, and both LeftPart and 
RightPart are null 


Sample Usage 
Program SampleUsageOfSp! i tD; 


type 
ParseType = string 2550, 
DelinType = stringt223, 


var 
SourcaStr, LeftPart, RightPart - ParseType, 
Delimiter Del isType, 
Found boolean; 
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($1 SplitD. PSL) 


BEGIN 
SourceStr °= ‘This is a test’, 
Delimiter °= ‘is’, 
SplitD(SourceStr, Delimiter, LeftPart, RightPart, Found); 
uriteln(Found), 
if Found then 
writeln(’Left part: », LeftPart, “¢ *, 
“Right part: >’, RightPart, °<'), 
uriteln, 
SplitD(SourceStr, ‘ 1s“, LeftPart, RightPart, Found); 
uri teln(Found); 
if Found then 
uriteln(’Left part: >, LeftPart, “< ", 
*Right part: >, RightPart, “<°); 
uriteln, 
SplitD(SourceStr, ‘test’, LeftPart, RightPart, Found); 
uriteln(Found), 
1f Found then 
writaln(’Left part: >, LeftPart, “< ", 
“Right part: ¥, RightPart, ‘< ); 
writeln; 
SplitD(’ abcd’, “BC’, LoftPart, RightPart, Found); 
writeln(Found) 
END. 


Running this test program produces the following output, ‘The less-than (¢) and 
‘greater-than (>) symbols are used here to delineate strings so that spaces, if present, 
can be seen more readily 





TRUE 
Left part: 2ThC Right part: > 1s a test¢ 


TRE 
Left part >This¢ Right part: da test¢ 


TRUE 
Left part: >This isa Right part: >< 


FALSE 
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Subprogram Listing of SplitD.PSL 





Variables 
SourceLen The string length of SourceStr 
Delimen ‘The string length of Delimiter 
Position Current position in SoureeStr 
Discussion 
‘This fundamental many possible in programs 
that process text strings. For a simple suppose that you are processing 
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Another possible use of Sp1itD occurs in “natural” language command processing, 
‘Suppose that you have a program which requests the user to input command strings 
like CREATE PLOT. The verb CREATE is an acceptable command in your language. 
Legal objects of this verb might be REPORT and FILE. If you make CREATE the 
delimiter, Sp1itD returns the object of the verb in RightPart. (The problem of 
uppercase and lowercase letters in this command syntax can be solved with the 
subprogram ConvUp in Chapter 11. See the introduction to this chapter and ConuUp 
in Chapter 11 for more details.) 











Modifications 
None 

SplitCh 

Name: S§plitCh 

Type: Procedure 

Purpose: To divide a string at a delimiter from a set of character 
delimiters 
Calling Sequence: SplitCh(SourceStr, DeliaSet, LeftPart, RightPart, 
Del ieChar, Found) 

Description 


A source string is searched left to right for the first occurrence of one of the 
delimiters specified in a delimiter set. If such a delimiter is found, the source string 
is split into two output strings—the part to the left of the delimiter and the part 
to the right. Each delimiter in the set must be a single character, but the set can 
contain any number of such characters (up to Turbo's maximum of 256). 


Input 


SourceStr string The Source string. It can be any length and may be 
specified as a variable or a literal in the calling 
statement. SourceStr’s type must be declared globally 
as ParseType. 
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DelinSet char The list of delimiters expressed as a sct. Each 
clement of the set is one character. The set can 
consist of any number of characters (up to 256) and 
may be specified as a variable or a literal in the 
calling statement. Del inSet’s type must be declared 
globally as Del 1aSetType. 


In addition, ParseType and Del isSetType must be declared global in the type block 
of your main program: 






type 
Parselype = stringl 255), 
DelinSetType = set of char, 


‘The number 255 is an example. Your maximum string length may differ 


Output 


LeftPart string The substring from SourceStr to the left of 
Delinchar. LeftPart is the null string if no delimiter 
‘match occurs in the source string, LeftPart is of 
type ParseType. 

RightPart string The substring from SoureeStr to the right of 
DelinChar. RightPart is the null string if no 
delimiter match occurs in the source string 
RightPart is of type ParseType. 


DelimGhar char The first character from Del iaSet found in 
SoureeStr. If Found is false, Del imChar is chr(@), 


Found boolean A flag that indicates whether a delimiter is found in 
SourceStr. If so, Found is true. If not, Found is false. 


Limitations and Error Conditions 


1tSourceStr isa null string, LeftPart and RightPart are null strings, Found is false, 
and Del ieGhar is set to chr (8) 


crust onc end of the source string, LaftPart or RightPart (as appropriate) is 
pul I Sour eaStr is a single character contained in Del aSet, Found is true, and 
both LeftPart and RightPart are null, 
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Sample Usage 
program SamplaUsage0fSplitCh, 


type 
ParseType = stringl255], 
DelinSatType = set of char; 


var 
SourceStr, LeftPart, RightPart: ParseType; 
DelinSet Del inSetType; 
Del imChar char; 
Found boolean; 

(SI SplitCh. PSL) 

BEGIN 


SourceStr <= ‘It’’s true! The secret ts mine.’; 

DelinSet = 0'.", 7, '1I, 

SplitCh(SourceStr, DeliaSet, LeftPart, RightPart, 

DeliaChar, Found); 
4f Found then 
uriteln(’ First sentence: “, LeftPart); 

uriteln, 

SplitCh(’ 420uidgets’, C’A’..'Z'J, LeftPart, RightPart, 
DelimChar, Found); 





writeln(’ Number: ‘, LeftPart); 
writeln(’ Item: ’, DelimChar + RightPart) 
END. 


Running this test program produces the following output: 





First sentence: It’s true 


Number: 429 
Item: Widgets 


Subprogram Listing of SplitCh.PSL 


Variables 
SourceLen ‘The string length of SourceStr 
Position Current position in SourceStr 
Discussion 
Tis snbprogram is useful whenever you need to parse a string based on a range 


oF collection of delimiters. For example, you can search for any uppercase letter, 
punctuation mark, numeral, etc. 
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‘Turbo's set type allows easy enumeration of delimiter ranges. Here are some set 
specifications to give you a few ideas: 





Louercaseletters «= (’a’..°2/J, 
PunctuationChars == '.', 4.0," °7, 154, "2h 
AnythingButSpace == Cehr(@).. chr(255)] - Cohr(32)3; 
RealNumberChars == C'#, °~", '.°, ‘EY, e', “@..°93, 
‘The disadvantage of sets is that each set member is restricted to a single character. 


‘The SplitD subprogram handles a delimiter of any length but is restricted to one 
delimiter at a time. 


Del nChar is the null character when no delimiter match is found. Be aware that 
a null string and a null character are different. A null string is a string devoid of 
any characters. When you use Turbo's built-in length function, a null string has a 
length of zero, A Turbo variable of type char consists of a single character, It always 
thas it length of exactly 1, even if this single character is the “null” character created 
by chr(@). (You can include the null character in DelisSet, and this subprogram 
recognizes the null character if it occurs in SourceStr. In these contexts, the null 
character has a length of 1 and prints as a space with wri te statements.) IfSourceStr 
is a null string, Found is always false. This holds even if Del ieSet is empty (C2) or 
contains the null character (Cehr(@)3), 


Modifications 


None 


SubStrD 





Name: SubSird 
Type: Procedure 
Purpose: To find a substring bounded hy two delimiters 


Calling Sequence: SubStrD(SourceStr, DeliaL, DelisR, ObjectStr, 
Position) 








Description 


SubStrD searches a source string left to right for the first occurrence of 4 given 
delimiter. If the delimiter is found, the search continues for the first occurrence 
of a second delimiter. If both delimiters are found, the substring bounded by the 
delimiters is returned. The two delimiters can be any length. 
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Input 
SourceStr 


Del im 


Del toR 


string 


string 


string 


The source string It can be any length and may be 
specified in the argument list as a variable or a string 
literal. Sour e@Str’s type must be declared globally as 
ParseType. 


‘The left (first) delimiter. It can be any length and 
may be specified as a variable or a literal in the 
calling statement. Delinl’s type must be declared 
globally as Del taType. 

‘The right (second) delimiter. It can be any length 
and may be specified as a variable or a literal in the 
calling statement. Delia's type must be declared 
globally as Del taType. 


‘The two string types, ParseType and Del iaType, must be declared globally in the 
type block of your main program 





type 
ParseType = string(255), 


Del imType 





stringC2@3, 


‘The lengths 255 and 20 are examples; your string lengths may differ. 


Output 
ObjectStr 


Position 


string 


integer 


‘The substring from SourceStr, bounded by Del il. 
on the left and Delia on the right. ObjectStr is set 
to the null string if the delimiters are not found in 
the source string. Ob jectStr is of type ParseType, 


If the delimiters are found, Position points to the 
character position in SourceStr where the first 
character of Deli occurs. If the delimiters are not 
found (sequentially) in SourceStr, Position is set to 
0 (zero), 


Limitations and Error Conditions 
Position is zero and ObjectStr is null if any of the following conditions is true: 


Del im is null, Del in is 


null, SourceStr is null or of length 1, or Del im. does not 


‘occur to the left of Del teR in the source string 
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If more than one pair of the delimiters occur in SourceStr, only the leftmost sub- 
string bounded by both delimiters is processed. If the delimiters occur adjacent to 
each other, Position points to the first character of Del 1aL, and Ob jectStr is null. 


Sample Usage 
program SampleUsageOfSubStrD; 
‘type 


ParseType = string(255J; 
DelinType = stringl 20); 


var 
SourceStr, ObjectStr = ParseType; 
Del inl, Delia Del iaType; 
Position integer; 


(SI SubStrD. PSL) 


BEGIN 
SourceStr «= “Phone number 1s (213) §55-1212", 
Delink === “('; 
DolinR = 7)"; 
SubStrD(SourceStr, DelinL, DeliaR, ObjectStr, Position); 
uriteln(’ Area code 1s “, ObyectStr), 
uritaln(’ Found at position”, Position, “ in source string’), 
writeln; 
SubStrD(‘ Mr. John Doe’, “Hr. “, ‘ ‘, ObjectStr, Position); 
(Note the space character *  * above each asterisk) 
uritaln(’ The gontlenan’’s first name is’, ObyectStr) 

END. 


Running this test program produces the following output: 





Area code is 213 
Found at position 17 in source string 


‘The gentleman’ s first name is John 
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Subprogram Listing of SubStrD.PSL 





Variables 
‘SourceLen ‘The string length of SourceStr 
LeftDLen ‘The string length of the left delimiter 
RightDLen ‘The string length of the right delimiter 
DelinLPos Position of the first character of Deli in the source 


string 
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Del inRPos Position of the first character of Del aR in the string 
formed by deleting all text from the source string to the 
left of and including Del im 


Discussion 


‘The delimiters can be identical. This is true in many practical uses of SubStrD. For 
example, a word is often defined as text bounded by a space on each side. If each 
delimiter is made to be a space, SubStrD finds the first word in the text string. 
(There are limitations to this simple approach, of course. If the leftmost character 
Of the source string is not a space, only an embedded word can be found, If two 
or more spaces occur consecutively, the null string is returned.) 


‘The output variable Position acts as a success or failure indicator. Position has 
4 positive value when the delimiters are found (success) and a zero value when 
they are not found (failure). Does it seem more logical to have Position point to 
the first character of the bounded substring instead of to the left delimiter? There 
isa pathological case that precludes this alternative. When the two delimiters occur 
juxtaposed, Ob jectStr is legitimately the null string. But you can’t point to the 
character position of the null string, Therefore, Position points to the left delimiter. 


Modifications 


None 


ParseKW 





Name: ParseKW 
Type: Procedure 
Purpose: To detect a keyword at a specific position in a string 


Calling Sequence: ParseKu(SourceStr, KuArray, KUCount, Position, 
Kulndex) 








Description 


Given a string array of keywords, Par seKUi detects whether a source string contains 
one of the keywords at a specified position. If so, the keyword is returned, and the 
Position variable is updated to point just beyond the keyword. The source string 
and keywords can be any length. This subprogram is usefull in “natural language” 
‘command processing and many other applications. 
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SourceStr string The source string. It can be any length and may be 
specified as a variable or a literal in the calling 
statement. SoureeSte’s type must be declared globally 
as Parselype. 

Kufrray string A string array containing the list of keywords. Each 
keyword can be any length. The array type must be 
declared globally as KuArrayType. 

KuCount integer The number of active elements in KUrray. KUCount 
must be at least 1 

Position integer The position in SourceStr where a keyword match is 


looked for. Position must be at least 1 and no more 
than the length of SourceStr. Position must be 
specified as a variable and cannot be a literal, 


Inaddition, the following global type declaration must appear in your main program. 
‘The numbers 255, 25, and 20 are examples. Your values may differ. 





= string(255), 


KufrrayType = array(1.. 25] of stringl2@3, 


type 
Par seType 
Output 
Position Integer 
KUlndex integer 


Current position in SourceStr. Position retains its 
input value if no keyword match is found. Position 
is positioned at the first SourceStr character past the 
keyword if a match is found. If the end of the 
keyword coincides with the end of SourceStr, 
Position is set to 0 (zero), 


Array index of the matching keyword or 0 (zero) if 
to keyword is found 


Limitations and Error Conditions 


KUllndex is set to zero and the procedure is bypassed if any of the following con- 
ditions is true: KMCount is less than 1, SourceStr is null, or Position is less than 
1 or greater than the length of SourceStr. 


If KuCount is less than the number of elements in KuArray, only the first KuCount. 
¢lements of the array are checked. Make sure that KuCount is not set higher than 
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the actual number of elements in the array. Spurious matches are possible in this 
case. 

The array of keywords is checked in ascending order. Be careful of ambiguity if 
your list of keywords contains similar strings. For example, suppose that DO appears 
in kKU@rray before DOODLE. Then DOODLE can never be detected because DO is 
always found first. Place DOODLE before DO to solve this potential problem. 


Sample Usage 
program SampleUsageOfPar sekW, 
type 


ParseType = stringl 2553; 
KufrrayType = arrayli, 25] of stringl202; 





var 
SourceStr ParseType; 
KuArray KurrayType; 
KiCount, Position, KWIndex + integer; 

(SI Parseki, PSL? 

BEGIN 
‘KuArrayCi) “MOE; 
KuarrayC2] <= * CHANGE, 
KArrayC3] = ‘COMPILE’; 
KUArrayC4] = ‘DELETE’; 
KuCount 
SourceStr + “CHANGE PAPER IN THE PRINTER’; 


Position 4; 
Parseku(SourceStr, KUArray, KUCount, Position, Kulndex); 
1f KUlndex > @ then 
begin 
writeln(’ Keyword (°, KuArrayCKWindex], “) found’); 
writeln(’ Position in source string is now’, Position) 
end; 
writeln; 
ParseKl(SourceStr, KuArray, KUCount, Position, KUIndex), 
if KuIndex > @ then 
writeln(’ Keyword *, KUlndex, “ found’) 
else 
writeln(’ Keyword not found’ > 
END 


Running this test program produces the following output: 


Keyword (CHANGE) Found 
Position in source string 1s now 7 


Keyword not found 


Subprogram Listing of ParseXKW.PSL 
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Variables 
TenpStr ‘Temporary string (a copy of one of the keywords) 
SourceLen The string length of SourceStr 
TempLen The string length of TenpStr 
Found boolean flag indicating whether or not a keyword match is 
found 
Discussion 


This kind of subprogram is a fundamental tool for lexical scanning. Suppose that 
you are writing a user interface that accepts “natural” language. (Examples are a 
‘compiler, adventure game, and input processor.) Your user is going to give com- 
mands from an allowable language. The interface must interpret these commands 
and take appropriate action. 


Consider the legal commands used to have the form of a verb followed by an object. 
Assume that the legal verbs are “TURN ON ", “TURN OFF ", and "BEGIN ”. (Note 
the terminating space for each verb.) These verbs are put in an array called Verbs. 
Another array called Ob ject contains PRINTER and COLOR MONITOR. Your in: 
terface could contain code like this: 








{ Vorb and Object arrays are defined) 
Position <= 1; 
ParseKW(SourceStr, Verbs, 3, Position, KWIndex); 


KUindex of 
uriteln(’Uhat are you talking about?’ ); 
begin 
ParseKu(SourceStr, Object, 2, Position, Newlndex), 
case Nowindex of 
@: writeln(” TURN ON what? ); 
1° uriteln(’ | should TURN ON the PRINTER’); 
2: writeln(’ 1 should TURN ON the COLOR MONITOR’ ) 
end 
end, 
2: Csimilar code to above except now TURNing OFF); 
3: Csimilar code to above except now BEGINning) 





Modifications 


None 
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ParseRN 








Name: ParseRN 
‘Type: Procedure 
Purpose: To detect a real number at a specific position in a string 
Calling Sequence: ParseRN(SourceStr, Position, Found, RealValue) 








Description 


ParseRN examines a source string for a real number beginning at a specified string 
position. If such a number is found, the value of the number is returned, and a 
Position variable is updated to the character in the source string just beyond the 
number, The source string can be any length 


Input 
SourceStr 


Position 


string 


intey 





‘The source string. It can be any length and may be 
specified as a variable or a literal in the calling 
statement. SouresStr’'s type must be declared globally 
as Parselype. 


‘The position in SourceStr where a real number is 
looked for. Position must be at least 1 and no more 
than the length of SourceStr. Position must also be 
specified as a variable and cannot be a literal. 


In addition, the following global type declaration must appear in your main program: 


type 
ParseType = stringlZ553, 


‘The number 255 is only an example. Your string length may differ, 


Output 


Position 


integer 


Current position in SourceStr. Position retains its 
input value if no legal real number is found. If a 
number is found, Position points to the first 
SourceStr character past the number. If the end of 
the number coincides with the end of SoureeStr, 
Position is set to 0 (zero). 
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Found boolean A flag indicating whether a real number was found in 
SourceStr, beginning at the input value of Position. 
If so, Found is true. If not, Found is false. 

RealValue real The real number found, if any. It is set to 8.0 if no 
number is found. 


Limitations and Error Conditions 


Found is false and RealValue is zero if the input value of Position is less than 1 
or greater than the length of SourceStr. 


Leading spaces are not allowed before or inside the number, The only characters 
used in Turbo’s real numbers are the plus sign (+), the minus sign (-), the decimal 
point (.), the exponential indicator (E or €), and the 10 digits from 0 to 9. On 
input, Position must be pointing to one of these characters, or no number is 
detected. 


‘The way Turbo (and this subprogram) interpret real number strings has several 
quirks. See the Discussion section 


Sample Usage 
program Samp]@UsageOfPar seRN, 


type 
ParseType = stringC2553;, 


var 
SourceStr » ParseType; 
Position integer; 
Found boolean; 
Realalue = real; 


(SI ParsoRN. PSL) 


BEGIN 
SourceStr =* ‘Rainfall 1s 452 inches’; 
Position == 13; 
ParseRN(SourceStr, Position, Found, RealValue); 





if Found then 
begin 
uriteln( Number found is:’, RealValue); 
uriteln(’ New position is: ", Position) 


end; 
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uriteln; 
Position == 1; 
ParseRN(’ -3. 28639, Position, Found, RealValue); 
if Found then 
begin 
uriteln(’ Number found 132 
uriteln(’New position 1: 
end 


RealValue); 
Position) 








END, 


Running this test program produces the following output: 





Number found is: 4, S2BeBa0000E+08 
New position is: 17 


Number found 1 
New position is: 8 


Subprogram Listing of ParseRN.PSL 
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Variables 
SourceLan ‘The string length of SourceStr 
Trtallen ‘The string length of a substring from Sour ceStr 
Code ‘Code returned from Turbo’s built-in val procedure 
Discussion 


‘The interpretation of strings as numbers (especially real numbers) isa great mystery 
in Turbo, Evident are a few glaring inconsistencies in what constitutes a real number 
‘expression for use in an assignment statement, a constant, and the val procedure, 
‘We can design ParseRN to interpret strings any way we want. Because Turbo has 
the built.in val procedure and because Par s0RX is likely to be used in environments 
invoking val, the easiest way to design Par s@RN is to take advantage of val (instead 
of writing our own lexical interpreter for real numbers). 


‘Two major surprises arise. The first is that val (and thus ParseRN) does not accept 
a plus sign leading a number although this is perfectly legal in an assignment state- 
ment. (A plus sign is OK after the exponential indicator.) If Position points to a 
plus sign, Found will automatically be false. You can solve this problem by explicitly. 
checking for the plus sign in your main program before calling Par seRN. If you find 
a plus sign, increment Position by one. 

‘The second surprise is that val accepts a real number beginning with a decimal 
point. This is specifically illegal in assignment statements. If you want consistency, 
you have to check explicitly for this case also. Sce the Limitations section of GetNunR, 
(Chapter 2) for further explanation of real number representations with val. 


Beware of some tricky cases with real numbers terminating before you might expect. 
‘The second example in the Sample Usage program is a good illustration. The ex: 
ponent (39) is too large for a real number. The 3 is OK, but the 39 is not. Therefore, 
val balks at the 9 and uses the 3 as the whole exponent. Position is on the 9 
when this example finishes 
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Modifications 


None 


ParseIN 





Name: ParselN 
‘Type: Procedure 


Purpose: To detect an integer number at a specific position in a 
string 


Calling Sequence: ParseIN(SourceStr, Position, Found, IntValue) 








Description 
ParselN examines a source string for an integer number beginning at a specified 
string position. If an integer is found, the value of the number is returned, and a 


Position variable is updated to the character in the source string just beyond the 
number. The source string can be any length. 


Input 


SourceStr string The source string. It can be any length and may be 
specified as a variable or a literal in the calling 
Statement. SourceSte’s type must be declared globally 
as ParseType. 


Position  intager The position in SourceStr where an integer number 
is looked for. Position must be at least 1 and no 
‘more than the length of SourceStr. Position must 
be specified as a variable and cannot be a literal, 


naddition, the following global type declaration must appear in your main program: 


type 
ParseType = stringt255), 


‘The number 255 is an example. Your string length may differ. 
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Output 


Position inte, 





Current position in SourceStr. It retains its input 
value if no legal integer number is found. If such a 
number is found, Position points to the first 
SourceStr character past the number. If the end of 
the number coincides with the end of SourceStr, 
Position is set to 0 (zero), 


Found boolean A flag indicating whether an integer number was 
found in SourceStr, beginning at the input value of 
Position. If so, Found is true. If not, Found is false. 


IntValue 





The integer number found, if any. It is set to 0 
(zero) if no number is found. 


Limitations and Error Conditions 


Found is false and IntUalue is zero if the input value of Position is less than 1 oF 
greater than the length of SourceStr. Leading spaces are not allowed before or 
inside the number. The only characters used in Turbo's integer numbers are the 
minus sign (-) and the 10 digits from 0 to 9. On input, Position must be pointing 
to one of these characters, or no number is detected. 


‘The way Turbo (and this subprogram) interprets integer number strings has some 
quirks, See the Discussion section. 


Sample Usage 
Program SampleUsageOfParseIN, 


type 
ParsaType = stringl255, 


var 
SourceStr * ParseType; 
Position = integer; 
Found = boolean; 
IntValue * integer; 


(SI ParseIN. PSL) 
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BEGIN 
SoureeStr == “UAREHOLSE 238 HAS THE LARGEST INVENTORY’; 
Position == 11; 

ParseIN(SouresStr, Position, Found, IntUalue); 
1f Found then 
begin 
writeln( Number found is‘, IntUalue); 
writeln(’ New position 1s: ", Position) 
end; 
uriteln, 
Position i= 1, 
ParseIN -45768, Position, Found, IntValue), 
1f Found then 
begin 
writeln(’ Number found is: “, IntUalue); 
writeln(’New position is: ", Position) 
a0 


Running this test program produces the following output: 





Number found 1s: 238 
New position is: 14 


Number found 1s: -4576 
Naw position is: 6 


Subprogram Listing of ParselN.PSL 
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Variables 
SouresLen ‘The string length of SourceStr 
TrialLen ‘The string length of a substring from Sour eeStr 
Code Code returned from Turbo's builtin val procedure 
Discussion 


‘This subprogram is the companion to ParseRN. ParseIN is used when integer num: 
bers are expected. ParseRN is used for real numbers. 
‘As explained in the Discussion section of Par seRN, there are pitfalls in using Turbo's 
built-in val procedure to interpret real numbers. You must also be careful in using 
val with integer numbers. The major surprise involves the plus sign. ‘The builtin 
val procedure (and thus ParseIN) does not accept a plus sign leading a number 
although this is perfectly legal in an assignment statement. If Position points to 
4 plus sign, Found is false. You can overcome this problem by explicitly checking 
for the plus sign in your main program before you call ParseIN. If you find a plus 
‘sign, increment Position by one. See the Limitations section of GetNual (Chapter 
2) for further explanation of integer number representations with val. 

Beware of some tricky cases with integer numbers terminating before you might 
expect. The second example in the Sample Usage program is a good illustration. 
‘The number (-45768) is outside Turbo's integer number range. The -4576 is OK, 
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but the 8 makes the expression too large for an integer number. Therefore, val 
balks at the 8 and uses -4576 as the whole number. Position is on the 8 when 
this example finishes. (If you anticipate your numbers being too large for integers, 
use Par seRN instead.) 


Modifications 
None 


11 





Converting 





This chapter presents four short subprograms that perform useful manipulations 
‘of text strings. Two of the subprograms deal with conversion between hexadecimal 
and integer numbers. Turbo maps the hex numbers 0000 through FFFF into the 
integers 0 through 32767 followed by -32768 through -1. This mapping can lead 
to confusion, especially when you have to manipulate integers for memory address 
calculations. Because Turbo does not provide any way to display hexadecimal num- 
bers, we have. IntToHex converts an integer number into a four-character hex string. 
‘The inverse function, HexTolnt, converts a four-character hex string into an integer 
number. 


ConvUp converts a text string into uppercase letters. Nonalphabetic characters are 
‘unaffected. This procedure provides a mechanism to “normalize” strings before 
they are interpreted by PlayTune or any of the searching or parsing routines. The 
‘companion subprogram, ConvLow, converts text strings to lowercase letters. 


IntToHex 
Name: /ntToHex 


‘Type: string function 
Purpose; To convert an integer number into a fourcharacter bex 
string 


Calling Sequence: IntToHex( IntNun) 














Description 


‘This subprogram is a function that converts any integer number into a four-character 
hexadecimal string. Leading zeros, if any, are included in the hex string. With 
IntToHex, you can make some sense of the integer variables you use for address 
calculations. By displaying these variables in hex format, you avoid the confusion 


207 
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that comes from Turbo’s mapping into the hex numbers 0000 through FFFF the 
integers 0 through 32767 followed by -32768 through -1 


Input 


IntNum integer The integer number you want converted into a 
hexadecimal number. IntNum can be a variable or a 
literal constant. 


In addition, you must specify in your main program the following global type 
declaration: 


ty 
String4 * stringl42, 


Output 


IntToHex string The function IntToHex retumns a four-character string 
that is the hexadecimal equivalent of IntNum, 


Limitations and Error Conditions 
None 


Sample Usage 
program SamplaUsage(f IntToHes; 


type 
String4 = stringt4, 


var 
IntNum integer; 


{SI IntToHex. PSL) 


BEGIN 
writeln(’ Enter integer from 32768 to 32767 (@ to end)’ ); 
repeat 
write’? *); 
readin(IntNum), 
uriteln(IntNum, * in decimal is hex”, IntToHex(IntNum)) 
until IntNum = 6 
END, 
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The following is sample output from the test program. You can use the values 
shown as test data. 






Enter integer from -22768 to 32767 (@ to end) 
2122 

122 in decimal is hex @87A 

7 21555 

21555 in decival is hex ABCD 

a 

82767 in decimal is hex 7FFF 


TA 

1 in decimal 1s hex FFFF 
? 4660 

4660 In decimal 1s hex 1234 
70 


@ in decimal is hex G08 


Subprogram Listing of IntToHex.PSL 





Variables 
HexChars ‘A typed constant char array containing the 16 hex 
characters (0-9 and A-F) 
Temp A work variable containing the byte currently being 


converted from IntNus 
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TompStr A work string containing the hex characters of the high- 
order byte of IntNum 


Discussion 
All right, it’s trivia quiz time, Here’s the question: What is the result if you add one 
to an integer variable that has the value 32767? Take a minute to think. We'll even 
make it a multiple-choice question. Your choices are the following: (1) 32768, (2) 
overflow error, (3) -1, (4) -32767, or (5) none of the above. 
Did you pick your answer? The correct answer is “none of the above.” The result 
of 32767 + 1 is -32768. Because of the way Turbo implements integer variables, 
this operation is the equivalent of adding hex 7FFF and 1, which is hex 8000, And 
in two's complement notation, hex 8000 is decimal -32768. 
‘The point of this diversion is that undesirable things can happen if you exceed 
‘Turbo's integer capacity. Be aware of these possibilities whenever you are ma- 
nipulating integers, including dealing with computer addresses. If you write a pro: 
‘gram that displays the addresses of some critical internal data, some addresses will 
be negative if you display them as integer values. Because Turbo provides no means 
of displaying numbers in hexadecimal, you can use IntToHex to do the job. 


Modifications 


None 


HexToInt 
Name: HexTolnt 


Type: integer function 


Purpose: To convert a bex string of one to four characters into an 
integer number 


Calling Sequence: HexToInt(HexStr ing) 











Description 


This subprogram, the opposite of IntToHex, isa function that converts a hexadecimal 
string of one to four characters into an integer number, With HexToInt, you can 
Write a program that requests keyboard input of a hexadecimal number and converts 
it into an integer value for use in calculations or as an address, 
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Input 


HexString string The one- to four-character hexadecimal string you 
‘want converted into an integer number 


In addition, you must specify in your main program the following global type 
declaration: 


tyr 
String4 


Output 


HexToInt integer The function HexToInt returns an integer number 
equivalent to the hexadecimal string in HexStr ing 





stringl4]; 


Limitations and Error Conditions 


HexString must be one to four characters long (or a null string). All of the char- 
acters must be legal hex digits (0-9, A-F) or blank spaces. Letters must be up: 
ppercase. You can use the Convlp subprogram to be sure that all letters are uppercase. 
A blank space is treated as if it were a zero digit. Thus, leading blank spaces are 
effectively ignored, but trailing or embedded blank spaces are treated as significant 
zeros. For example, the string ’ ABC’ (one leading space) is treated as ’ @ABC’ , but 
“ABC * (one trailing space) is treated as ’ ABC’. When an illegal character is found 
(not 0-9, A-F, or a blank space), HexToInt returns zero as the integer number for 
the hex string You can change the illegal return value as shown in the Modifications 
section. 


Sample Usage 
program SampleUsage0fHexTolnt; 


type 
Stringd = stringC4];, 


var 
HexString: String4; 


(SI HexTolnt. PSL? 


302 ‘TURBO PASCAL PROGRAM LIBRARY 





‘BEGIN a 
writeln(’Enter 1 to 4 character hex number (FFFF te end)’ ); 
repeat 


write’? “); 
read|n(HexString); * 
writeln(HexString, “ hex is decimal *, HexTolnt(HexString)) 2 
until HexString = “FFF” 
‘END. 


‘The following is sample output from this test program. You can use the values 
shown as test data, Note that the fourth number entered (123R) contains an illegal 
hex character and is converted into zero as a result. 


Enter 1 to 4 character hex nuaber (FFFF to end) 
7 ABCD 

ABCD hex is decimal -21555 

7 7FFE 


FFF hax 1s deciaal 32767 
278 

7 hex 1s decieal 122 
7:123R 

1ZRR hex 1s decieal 8 
71234 


1234 hex 1s decimal 4660 
? FFF 





FFFF hex 1s decimal -1 


Subprogram Listing of HexTolnt.PSL 











Variables 
J ‘The position within the string where the character 
currently being converted into hex is located 
Total ‘The accumulated total of the value of HexToInt 
tult ‘The multiplier for each hex position (1 for the low-order 
position, 16 for the next position, 256 for the next 
position, and 4096 for the high-order position) 
Digit ‘The numeric value of the hex digit being converted 
Temp ‘The hex character being converted 
Discussion 


HexToInt scans the character string from right to left (low order to high order) 
‘one hex digit at a time, determining the numerical value of the hex digit and 
‘multiplying the digit by the appropriate power of 16 (1, 16, 256, or 4096), The 
‘sum of these values is the decimal equivalent of the hex character string, 
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Modifications 


1. To make a blank space an illegal character instead of an implied zero, 
delete the line indicated by (Hod. #1). 


2. Change @ in the indicated line in order to alter the output of HexToInt 
when an illegal character is found. Depending on your application, you 
may need to differentiate between an illegal zero and a legal one. We 
chose zero as the illegal value because zero is relatively easy to check in 
your main program. (That is, if HexString is all zeros, then the result is 
legal.) If you want, change the zero in the indicated line to -1 or 32767 
or any valid integer value you choose. 


ConyUp 





Name: Convt/p 
Type: Procedure 
Purpose: To convert a string to uppercase letters 
Calling Sequence: ConvUp(ConvString) 








Description 
This procedure converts to uppercase any lowercase letters in a string, Nonalpha- 
betic characters are unchanged. Convlp is useful as a preprocessor for strings before 


they are passed to one of the searching or parsing subprograms. Convlp can be 
uused.also to rectify strings for PlayTune and HexToInt. 


Input 


ConvString string ‘The string to be converted. It can be any length and 
must be specified as a variable in the calling 


statement 
In addition, you must specify in your main program the following global type 
declaration: 

type 


string255 = stringl255), 
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Output 
ConvString string The same string, now converted. Any lowercase 
ate eatin seo 
letters. Other characters are unchanged. 


Limitations and Error Conditions 


None 


Sample Usage 
program SanploUsageOfConvUp, 


type 
‘String255 = stringC2552, 


var 
ConuString: String255, 
($1 ConvUp. PSL) 


‘BEGIN 
ConvString ‘= ‘Give Jack $180. 
ConvUp(ConvStr ing); 
wr iteln(GonvString) 





Running this test program produces the following output: 
GIVE JAK $100. 46 


Subprogram Listing of ConvUp.PSL 
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Variables 
R) Looping index 


Discussion 


A typical use of this subprogram is to rectify strings before a sort, search, or parse 
is performed on them. For example, suppose that your main program takes com- 
mands from the user in “natural” language. Let’s say that your program needs to 
parse an input string at the keyword START. The problem is that your user may 
type Start, start, START, or even something like StART. An expedient approach is 
to run the input string through ConvUp before searching the string, Then you need 
to check only the converted string for START in order to cover all these possible 
ceases, 


Modifications 
None 


ConvLow 





Name: Convlow 
Type: Procedure 
Purpose: To convert a string to lowercase letters 
Calling Sequence: ConvLow(ConvString) 








Description 


‘This procedure converts to lowercase any uppercase letters in a string, Nonalpha- 
betic characters are unchanged. ConvLow is useful as a preprocessor for strings 
before they are passed to one of the searching or parsing subprograms, 


Input 


ConuString string The string to be converted. It can be any length and 
‘must be specified as a variable in the calling 
statement. 
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In addition, you must specify in your main program the following global type 
declaration: 


ty 
string255 = string(255]; 


Output 
ConvString string The same string, now converted. Any uppercase 


letters are replaced by the equivalent lowercase 
letters, Other characters are unchanged. 


Limitations and Error Conditions 
None 

Sample Usage 

program Samp UsageOfConvLow, 


type 
String255 = stringt2552; 


var 
ConvString: String255; 


($1 ConuLow. PSL) 


BEGIN 
ConvString '= "Give Jack $100. 46°; 
Convlow(ConvString); 
uriteln(ConvString? 

END. 


Running this test program produces the following output: 


give jack $108, 46 
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Subprogram Listing of ConvLow.PSL 





Variables 
TostChar Character from ConvString 
J Looping index 
Discussion 


Because lowercase letters are 32 positions higher than uppercase letters in the 
ASCII sequence, ConvLow simply adds 32 to the numeric representation of any up- 
percase letter in the string, 


ConvLow is the companion subprogram to Convp. Each subprogram can be used 
in a similar way. See ConvUp for further explanation. 


Modifications 


None 
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Mathematics and Engineering 








‘This chapter presents 15 subprograms for mathematicians and engineers. The em- 
phasis is on practical numerical techniques required in a large variety of engineering 
problem solving. The subprograms can be grouped into five major subdivisions: 

1, Library functions (hyperbolic functions, exponentiation) 

2, Vector mathematics (three-dimensional vector products) 

3, Matrix arithmetic (two-dimensional matrix manipulation ) 

4, Functional analysis (roots, derivatives, etc., of a function) 

5. Differential equations (ordinary differential equation solver) 
‘The library functions are Power and HyperLib. CrossPr and DotPr are the vector 
math subprograms. The matrix arithmetic set contains HatShou, tatAdd, MatSub, 
Mattult, HatTrans, Matiny, and Determ. Functional analysis subprograms consist of 
Integral (definite integrals), Root (real roots), and Der iv (derivatives), Dif fEgn 
solves ordinary differential equations. 
‘Taking advantage of Pascal's flexibility, we developed some tools in Turbo to fa- 
cilitate representation of possibly awkward mathematical constructs, These tools 
include special data structures for vectors and matrices. We developed also a tech- 
nique to express your own functions. Generally, subprograms in one subdivision 
can be easily linked together in your main programs to form cohesive units. 
‘Turbo Pascal has two limitations that hinder us mildly. One is that array dimensions 
must be declared explicitly and stay fixed between main programs and subprograms. 
‘Suppose that you want a general matrix multiplication subprogram for your library. 
You need some way to pass the different array dimensions to the subprogram each 
time it is called. But Turbo doesn't permit such activity, (Turbo does not support 
conformant-array parameters, a feature designed to solve this problem. Only a few 
Pascal compilers implement these parameters.) 
‘The second limitation is that Turbo does not allow passing 10 a subprogram the 
name of a function as a parameter. (Again, this is permitted in some Pascal com- 
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pilers.) We wanted to do this in the functional analysis subprograms so that they 
could be written as general library routines. 

Our solution to both problems is similar. We require certain global declarations 
in the main programs. (These declarations remain in force inside the subprograms. ) 
‘Through careful global specifications in a few key places, only minimal programming 
changes are needed for new applications. These techniques are developed and 
explained in the appropriate subprogram write-ups. 


Power 





Name: Power 
‘Type: real function 
Purpose: To perform exponentiation of real numbers 
Calling Sequence: Power (Nuaber, Exponent) 











Description 
Power raises a positive number to any power. 
Input 

Nunber real Number on which to perform exponentiation. Nuaber 
‘must be greater than zero but does not need to be 
an integer value. 

Exponent real Exponent to which Number is raised. Exponent can be 
positive, negative, or zero but does not need to be an 
integer value 

Output 

Power real The function Power returns Nunber raised to the 

Exponent power. 


Limitations and Error Conditions 


If Number is negative or zero, Power returns a value of zero. A fatal run-time error 
occurs if you try to calculate a result outside Turbo's real-number range. Results 
must be greater than 1.0E-38 and less than 1.0E+38. 
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Sample Usage 
Program SampleUsageOfPower, 


Number, Exponent, Result: real; 
(SI Power. PSL? 


BEGIN 
Nuber == 2.0, 
Exponent <= 5.8; 
Result == Pouer(Nuaber, Exponent); 
writaln(Number'4'2, “ to the’, Exponent 5:2, 
sibs ts’, Result6:2), 
Result == Power(23.0, 1/3) 


writeln(’ Cube root of 23 te Result) 


Running this test program produces the following output: 





@8 to the 5.28 power is 32.00 
Cube root of 23 1s 2. B438669778E+00 


If Number and Exponent are set to 5 and -2 before you invoke Power, then Result 
is 0.04 afterward. If Nunber is -3 and Exponent is anything, Result is zero, If Number 
is zero and Exponent is anything, Result is zero. Note that Power can use input 
arguments that are variable names or numeric constants. 


Subprogram Listing of Power.PSL 
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Variables 
None 

Discussion 
To implement exponentiation in any (positive) base, this function makes use of 
the natural (base ¢) functions exp and In. Power allows the Pascal statement 
R'=Pouer(X, Y) to be the equivalent of R= X*Y in BASIC for a positive X. Don’t 
overlook the application of this function in calculating roots as well as powers 
‘Turbo Pascal has the sgrt function for square roots, but Power calculates other 
roots also (cube roots when Exponent is 1/3, inverse fourth roots when Exponent 
is -0.25, etc.) 


Modifications 


1, To eliminate detection of the error condition, delete the three lines 
indicated by (Mod. #1). This change slightly speeds up the calculation. 
(We recommend this modification only if you do error checking in your 
mainline program and you need increased speed because of high-volume 
‘use of Power.) 


2. Ifyou want to allow Nuaber to be zero, add the following lines after the 
indicated else statement: 


if (Number = @.8) and (Exponent * 8.8) then 
Power °= 1.8 
else 


3, To cause your program to end abnormally if Nuber is not positive 
instead of simply returning a value of zero), change the line indicated 
by (Hod. #3) to 


Power <* Number / 8.8 (force error) 
This change causes Power to divide by zero when the error condition 
occurs, forcing a run-time error. Generally, a better course of action is 


to display a descriptive message and then end normally, but sometimes 
forced error is expedient during testing. 
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HyperLib 
Name: Hyperlib 
Type: real function 
Purpose: To calculate the byperbolic functions sinb, cosh, and tanh 
Calling Sequence: Sinh(Nunber), Cosh(Nunber ), Tanh(Number ) 











Description 
HyperLib is a minilibrary consisting of the three common hyperbolic functions sinh, 
‘cosh, and tanh. These functions are the hyperbolic sine, hyperbolic cosine, and 
hyperbolic tangent, respectively. HyperL 1b contains three separate subprograms, To 


invoke one, select Sinh, Cosh, or Tanh, 
Input 


Number real Argument of the hyperbolic function. Number can 
have any real value (positive, negative, or zero). 


Output 
Sinh real Function yielding the hyperbolic sine of Number 
Cosh real Function yielding the hyperbolic cosine of Nunber 
Tanh real Function yielding the hyperbolic tangent of Number 


Limitations and Error Conditions 


To prevent overflow, you must not set the absolute value of Number greater than 
88. 


Sample Usage 
program SampleUsageOfHyperL ib; 


var 
Number, SinhResult, CoshResult, TanhResult: real; 


(SI HyperLib, PSL? 
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‘BEGIN 
Coane *Sinh(X)" =13, “Cosh(X)’ 13, * Tanh(X)’ +13), 





1.8 
bref Nunbor 10 do 





writeln(Number -1:2, Slakenttusis, CoshResult 13:5, 
TanhResult 13:5); 
Number '= Number + 8.5 
end 
END. 


Running this test program produces the following abbreviated table of the hyper- 
bolic functions: 





Subprogram Listing of HyperLib.PSL 
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Variables 
None 


Discussion 


‘The hyperbolic functions are useful in various disciplines of engineering, applied 
‘mathematics, and pure mathematics. The Turbo function exp is used to define these 
functions. 


Because tanh(X) = sinh(X) / cosh(X), the Tanh function has been implemented 
by invoking Sinh and Cosh. Thus, you must include all three functions from HyperLib 
if you plan to use Tanh. If you just need Sinh or Cosh, you can include only that 
function in your application, 


The reciprocals of the functions in HyperLib are the hyperbolic cosecant, secant, 
and cotangent. You can add these and the inverse hyperbolic functions to HyperLib 
if you like. The functional definitions can be found in many math texts and other 
references. Appendix E of the IBM BASIC manual is one source you may already 
have, 


Modification 


‘The Sinh and Cosh functions cause numeric overflow if either is invoked when 
Nunber has an absolute value greater than 88. To avoid this overflow, insert the 
following five lines immediately after the begin statements indicated by (Hod, #1): 





if Number > 88.8 then 
Number == 88,8 
else 
1f Number < - 88. then 
Number == -88.2; 


‘These lines cause the functions to retum the largest real numbers (positive or 
negative as appropriate) possible with standard IBM Turbo Pascal precision. 


CrossPr 





Name: GrossPr 
Type: Procedure 
Purpose: To calculate the cross product of two vectors 
Calling Sequence: CrossPr(VectorA, VectorB, Vector) 
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Description 
‘The cross product of two vectors is a vector. CrossPr calculates the cross product 
of two input vectors. All vectors are three-dimensional. They are mathematically 
specified in Cartesian coordinates with an X, a Y, and a Z component. In Turbo, 
a special record type is used to represent the vectors. 


Input 


VectorA record The first input vector. It consists of an X, a Y, and a 
Z component. Each component is a real number, 


VectorB record The second input vector. It consists of an X, a Y, and 
2 Z component. Each component is a real number. 


‘The following global type declaration must be specified in your main program: 






type 
VectorType = 
vacord 
% Y, 2: real 


end 
‘This type declaration creates a special data type for representing each vector. See 
the Discussion section for details. 

Output 


VectorS record — The cross product of UectorA and VectorB, Vector 
consists of an X, a Y, and a Z component. Each 
‘component is a real number. 


Limitations and Error Conditions 
None 
Sample Usage 
program Samp letlsageOfCrossPr; 
type 
VectorType = 
record 


x Y, 2) real 
end; 
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var 
VectorA, VectorB, VectorC: VectorType; 


(SI CrossPr. PSL) 


BEGIN 

VactorA.X ‘+ 1.5; UectorA.Y == 2.9; Uactora Z 

VectorB.X = 3.0, UactorB.Y «= 4.8; VectorB.Z tee! 

CrossPr(VactorA, VectorB, VectorC), 

writelnt’ YectorA(x, ¥,2) = (, UectorA. X:7+ 2 Vectora ¥:7:2, 
Vector. 2:7:2, “y 

writeln(’ VectorB(x, ¥,2) = (°, VectorB. X:7« z VectorB.¥:7:2, 
VectorB 2:72, °)'); 

writeln(’ YectorG(x, ¥,2) = (°, VectorG.X:7'2, Vectorl. ¥:7:2, 
Vector€ 2:7:2, *)) 











END. 
Running this test program produces the following output: 





VectorA(x,¥,2) = ( 1.58 208 -1.00) 
VectorB(X,¥,2) = ( 388 4.08 5.28) 
VectorC(x,¥,2) = ( 14.08 -18.58 8.00) 


Subprogram Listing of CrossPr.PSL 





Variables 
None 


Discussion 


Vectors occur frequently in physics and engineering problems, especially in the 
area of force field kinetics. Vector attributes are a magnitude and a direction in 
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three-dimensional space. With standard Cartesian coordinates, a vector is specified 
by three real numbers corresponding to its components in the X, Y, and Z directions, 
For notational convenience, we developed the record data type VectorType to 
represent vectors. Each vector is specified by a record having three fields: X, Y, 
and Z. Each of these fields consists of a real number (positive, negative, or zero) 
that represents the appropriate vector component. Thus, you can reference the 
‘components of, say, UectorSample with the specifications VectorSample. X, 
VectorSample. Y, and VectorSanple. 2. By the way, the field identifiers X, Y, and Z 
are unique only within the records in which they are defined. Therefore, you can 
still use X, Y, and Z as variable names in the same block(s) in which you use the 
records. 


Given two input vectors, the resultant cross product has a magnitude equal to the 
product of the magnitudes of the two input vectors multiplied by the sine of the 
angle between them. The direction of the resultant vector is perpendicular to the 
plane containing the two input vectors. The order of the two input vectors is 
important because “A cross B” does not equal “B cross A” if A and B are the two 
original vectors, In fact, reversing the specification will result in a new resultant 
vector, with each component having a sign opposite from that of the old resultant 
vector. That is, (A X B) equals (B X A), in which X is the conventional notation 
denoting the cross product. 


Modifications 


None 


DotPr 





Name: DotPr 
‘Type: real function 
Purpose: To calculate the dot product of two vectors 
Calling Sequence: DotPr(VectorA, Vector) 











Description 


‘The dot (or scalar) product is a single real number. The two input vectors are 
three-dimensional. They are mathematically specified in Cartesian coordinates with 
an X, aY, and a Z component. In Turbo, a special record type is used to represent 
the vectors. 
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Input 


Vectora record The first input vector. It consists of an X, a Y, and a 
Z component. Each component is a real number. 


YectorB record The second input vector. It consists of an X, a Y, and 
@ Z component. Each component is a real number, 


The following global type declaration must be specified in your main program: 






type 
UsetorType = 

record 
X,Y, 2: real 


‘end, 


‘This type declaration creates a special data type for representing each vector, See 
the Discussion section of the CrossPr subprogram for details. 


Output 


DotPr real The function DotPr returns the dot product (a 
scalar) of VectorA and VectorB, 


Limitations and Error Conditions 
None 


Sample Usage 
program SampleUsageOfDotPr; 


type 
VectorType = 
record 
X.Y, 2° real 


end, 

var 
Vector, VectorB = VectorType; 
Result real; 


(SI DotPr. PSL? 
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BEGIN 
UsctorA.X = 1.5, UsctorA.Y == 20, UsctorA.Z == -1.0, 
VectorB.X °= 3.8, VectorBY == 4.8; VectorB2 := 5.8; 
Result <= DotPr(UectorA, VectorB); 
uriteln(’ VectorACX,Y,2) = (, UectorA.X:7:2, VectorA, ¥:7:2, 

VectorA.2:7:2, °°); 
uriteln(’ VectorB(X,¥,2) = (, VectorB. VectorB.¥:7:2, 
VectorB.2:7:2, °°), 
uriteln(’ Dot Product =“, Result 6:2) 








Running this test program produces the following output: 





VectorACx,¥,2) = ( 1.58 208 -1.00) 
VectorB(x,¥,2) *( 3.28 4.08 5.08) 
Dot Product = 7.58 


Subprogram Listing of DotPr.PSL 





Variables 


None 


Discussion 
DotPr uses the same three-dimensional vector representation described in the De- 
scription and Discussion sections of the CrossPr subprogram. The identical record 
data structure Vector Type is used also to make these two subprograms compatible 
in the same main program. 
The dot product is a scalar quantity described by one real number. Thus, this 
subprogram is a function, whereas CrossPr (producing a vector) is a procedure, 


‘The dot product is defined as the product of the magnitudes of the two input 
vectors multiplied by the cosine of the angle between them. Unlike the order of 
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the input vectors for GrossPr, the order of the two input vectors is not important 
here because “A dot B" does equal “B dot A” if A and B are the two original input 
vectors. 

Modifications 
None 


MatShow 
Name: MatShow 
‘Type: Procedure 
Purpose: To display the contents of a matrix 
Calling Sequence: MatShow(MatrixA) 











Description 


HatShow displays on the current output device (usually the screen) the values of 
a matrix. The matrix must be two-dimensional and square, and it must contain 
values of type real. HatShow is intended for simple fixed-format applications, See 
the more flexible subprogram Show2Arr (Chapter 4) for additional capability. 


Input 
Matrix real. An array containing the matrix to be displayed 


‘The following global const and type declarations must be specified in your main 
program: 





const 
MatrixSize = 3; 


type 
HatrixType = arrayCl..MatrixSize, 1..MatrixSize] of real; 
‘The constant MatrixSize defines the size of the square array, (That is, the value 
of MatrixSize is the number of elements on a main diagonal of your matrix.) 
Matr ixSize can be any positive integer. The value 3 is used here only as an example. 
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Output 


‘The clements of HatrixA are displayed on the current output device (normally the 
screen), 


Limitations and Error Conditions 


For this formatting, it is assumed that each element in your matrix has an absolute 
value less than 1,000,000 and that no more than two significant digits are to the 
right of each decimal point. If these restrictions are too severe, refer to the Mod- 
ification section or the Show2Arr subprogram. 


Sample Usage 
Program Samp] @UsageDfMatShow, 


const. 
MatrixSize = 3; 


type 
MatrixType = arrayCt MatrixSize, 1, HatrixSize] of real; 


var 
MatrixA : HatrixType; 
IJ integer; 


($1 MatShow, PSL) 


BEGIN 
for I = 1 to MatrixSize do 
for J := 1 to MatrixSize do 
MatrixACl, JJ = 1" J /29; 
MatShou(Matr 1 xf) 
END. 


Running this test program produces the following output: 


0.508 10 1.58 
1.00 2.08 3.08 
1.50 3.00 4.58 
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Subprogram Listing of MatShow.PSL 





Variables 
1 ‘Subscript pointing to the current row of the matrix being 
referenced 
J Subscript pointing to the current column of the matrix 
being referenced 
Discussion 


‘Two-dimensional matrices occur frequently in the solutions of mathematical and 
engineering problems. We include several matrix manipulation subprograms in this 
book. For all these subprograms, we have assumed that the matrices are square. 
In the discussion of subsequent subprograms, however, we'll show how certain 
nonsquare matrices can be accommodated. 

HatShow displays the values of HatrixA in the conventional “square table” form. 
‘One line of output displays the values of one row of the matrix. If you use HatShow 
‘with a value of MatrixSize larger than 8, the subprogram will cause displayed output 
from one row to “spill over” to the next line of output. 

‘Turbo Pascal does not provide a convenient method of passing differently sized 
arrays to the same subprogram. This means that the matrix dimension (Matr1xSize) 
must be declared globally. If your main program uscs several arrays that differ in 
size, you can use HatShou in two ways for different cases. 
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‘One way is to declare (in your main program) all the different sizes of your arrays, 
This necessitates setting multiple constants (for example, MatrixSizeA = 4, 
MatrixSizeB=6, HatrixSizeC = 7, etc.) and using them in appropriate var decla- 
rations for each matrix. Then multiple copies of MatShow can be created (named 
MatShou, HatShouB, MatShowl, ctc.) when the variable HatrixSize becomes 
MatrixSizeA in MatShouA, MatrixSizeB in MatShowB, and so on, When you want to 
display a matrix, you'll have to know its size beforehand and invoke the correct 
procedure. 

‘The second method is to set MatrixSize in your main program to the largest value 
required for any of your matrices. Then HatShou can be invoked for every matrix. 
Matrices of smaller than maximum size, however, are displayed with unpredictable 
values for the extraneous array elements, 


Modification 


Each matrix element is currently displayed with 18:2 format. This accommodates 
real numbers with an absolute value less than 1,000,000 and no more than two 
significant figures to the right of the decimal point, If this format is insufficient, 
you may change 18:2 to anything allowed for real numbers. 


MatAdd 
Name: MatAdd 
Type: Procedure 
Purpose: To add two matrices 
Calling Sequence: MatAdd(HatrixA, MatrixB, MatrixC) 














Description 
MatAdd adds two matrices together and stores the result in a third matrix, All 
matrices are two-dimensional, square, and the same size. All of them contain values 
of type real 

Input 
Matrix real Array containing the first matrix to be summed 
MatrixB real Array containing the matrix to be added to Hate ix 
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The following global const and type declarations must be specified in your main 
Program: 





NatrixType = arrayC. MatrixSize, 1. MatrixSize} of real; 
‘The constant MatrixSize defines the size of the square arrays. (In other words, 
the value of MatrixSize is the number of elements on the main diagonal of each 
of your three matrices.) HatrixSize can be any positive integer. The value 3 is 
only an example. 
Output 
MatrixC real Array containing the sum of MatrixA and Hatr {xB 


Limitations and Error Conditions 
None 

Sample Usage 

program Samp eUsageOftatAdd; 


const 
MatrixSize = 3; 


type 
MatrixType = arrayCi. MatrixSize, 1. MatrixSize of real; 


var 
Matrix®, HatrixB, MatrixG = MatriaType; 
LJ integer; 


(SI MatAdd. PSL) 
($I MatShow. PSL) 
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‘BEGIN 
for 1 == 1 to MatrixSize do 
for J == 1 to MatrixSize do 
begin 
MatrixACl, JJ = 1* 5/28; 
MatrixBCI, JJ == 1 - J 


end; 
Mathdd(MatrixA, MatrixB, MatrixC); 
writeln(’ MatrixA ="); MatShow(MatrixA); 
uriteln(’MatrixB ="), MatShow(Matr ixB); 
writeln( MatrixA + MatrixB =), MatShow(Matrix) 


Running this test program produces the following output: 





Subprogram Listing of MatAdd.PSL 
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Variables 
1 Subscript pointing to the current row of the matrix being, 
referenced 
J ‘Subscript pointing to the current column of the matrix 
being referenced 
Discussion 


‘The mathematical definition of matrix addition requires that both input matrices 
be identical in size. They don’t need to be square, however, as long as each matrix 
has the same number of rows and each matrix has the same number of columns. 
But the number of rows does not have to equal the number of columns. 


You can use MatAdd to add two matrices that aren’t square. To add the matrices, 
set MatrixSize to the number of rows or the number of columns, whichever is 
greater. This creates square matrices with extrancous rows or columns. (Some 
memory is thus wasted.) MatAdd works even though your matrices contain some 
unneeded elements, You must keep track of which parts of the square matrices 
are relevant. The numbers you get in the unneeded row(s) or column(s) will be 
unpredictable. You might want to sct the extrancous array elements to zero in your 
input matrices before you invoke MatAdd. Then the resulting sum matrix will have 
zeros in the same (appropriate) locations. Therefore, the extraneous array elements 
will stand out more easily if you display the matrices with a procedure such as 
MatShow. Setting the unneeded elements to zero also avoids the small possibility 
of overflow that could result from adding two (unknown) large numbers, 


Modifications 


None 


MatSub 





Name: MatSub 
‘Type: Procedure 
Purpose: To subtract one matrix from another 
Calling Sequence: MatSub(MatrixA, MatrixB, MatrixC) 
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Description 
MatSub subtracts one matrix from another and stores the result in a third matrix. 


All matrices are two-dimensional, square, and the same size. All of them contain 
values of type real 


Input 
Matrix real Array containing the first matrix 


MatrixB real Array containing the matrix to be subtracted from 
HatrixA 

‘The following global const and type declarations must be specified in your main 

program: 





const 
MatrixSize = 3; 


type 
MatrixType = arrayCt. MatrixSize, 1. MatrixSize] of real; 


‘The constant MatrixSize defines the size of the square arrays. (That is, the value 
of MatrixSize is the number of elements on the main diagonal of each of your 
three matrices.) MatrixSize can be any positive integer. The value 3 is only an 
example, 


Output 
MatrixC real Array containing the result of Matrix - Matr ixB 


Limitations and Error Conditions 
None 


Sample Usage 
program SampleUsageOfMatSub; 


const 
MatrixSize = 3; 
type 
MatrinTyne = arrayC1. MatrixSize, 1. MatrixSize] of real; 
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var 
MatrixA, MatrixB, MatrixC « MatrixType; 
Ld » integer; 
(SI MatSub. PSL) 


(SI MatShou. PSL) 


BEGIN 
for I := 1 to MatrixSize do 
for J := 1 to HatrixSize do 
begin 
MatrixACI, JJ == 1 #5 7/28; 
MatrixBCl, J] == 1- J 
‘end; 
MatSub(MatrixA, MatrixB, MatrixC); 
writeln( MatrixA =’); MatShow(MatrixA), 
writeln(’MatrixB ="); MatShow(Matr!xB); 
uriteln(’MatrixA - MatrixB ="); MatShow(HatrixC) 
END. 


Running this test program produces the following ouput: 


Pres 
eee 
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Subprogram Listing of MatSub.PSL 





Variables 
1 ‘Subscript pointing to the current row of the matrix being 
referenced 
J ‘Subscript pointing to the current column of the matrix 
being referenced 
Discussion 


In the Discussion section of the HatAdd procedure, the comments pertaining to 
onsquare matrices are equally valid for MatSub, Refer to that section for details, 


Modifications 


None 


MatMult 





Name: MatMult 
Type: Procedure 
Purpose: To multiply two matrices 
Calling Sequence: fHattult(MatrixA, MatrixB, HatrixC) 
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Description 
Hattult multiplies two matrices and stores the result in a third matrix. All matrices 
are two-dimensional, square, and the same siz. All of them contain values of type 
Input 
Matrix real Array containing the first matrix of the multiplication 
MatrixB real Array containing the matrix that multiplies Matrix 
‘The following global const and type declarations must be specified in your main 





Program: 
const 
YatrixSize = 3; 
type 
NatrixType = arrayCi. tatrixSize, 1, HatrixSize] of real, 





‘The constant HatrixSlze defines the size of the square arrays. (In other words, 
the value of HatrixSize is the number of elements on the main diagonal of each 
of your three matrices.) MatrixSize can be any positive integer, The value 3 is 


only an example. 
Output 
NatrixC real Array containing the result of Hate ix® multiplied by 


MatrixB 


Limitations and Error Conditions 
None 
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Sample Usage 
Program SampleUsageOfMattult; 


const 
MatrixSize = 3; 





type 
NatrixType * arrayC. MatrixSize, 1. MatrixSize) of real 
var 
MatrixA, MatrixB, MatrixC © MatrixType; 
LJ integer; 
($1 MatMult, PSL) 
(31 NatShow. PSL) 
BEGIN 


for I = 1 to MatrixSize do 
for J :* 1 to'MatrixSize do 
begin 
MatrixACl, JJ = 18d / 28; 
MatrixBCI, JJ = 1 - J 
‘and; 
MatHult(MatrixA, MatrixB, HatrixC), 
uriteln(’MateixA =), MatShou(MatrixA); 
writeln( MatrixB =’); MatShow(Matr 1x8), 
uriteln(’MatrixA * MatrixB ="); MatShow(MatrixC) 
END, 


Running this test program produces the following output 


1.08 1.50 
200 3.08 
3.00 4.58 
108-208 
82 8 -1.00 
108 8.00 
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Matrix = MatrixB = 
4.00 1000-200 
8 200 = 4.00 
12.08 30 86-6008 


Subprogram Listing of MatMult.PSL 





Variables 
1 Subscript pointing to the currently referenced row of 
Mate ixA or MateixC 
J Subscript pointing to the currently referenced column of 
MatrixB or MateixC 
K ‘Subscript pointing to the currently referenced column of 
HatrixA or the currently referenced row of HatrixB 
TenpSun ‘Temporary (partial) value of the multiplication 
Discussion 


‘Multiplication of two-dimensional matrices is defined only when the number of 
‘columns in the first matrix is equal to the number of rows in the second matrix. 
‘Of course, this compatibility is automatic when the two matrices are square. 
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‘You can use HatHult for nonsquare matrices by applying the technique explained 

in the Discussion section of the MatAdd subprogram. Refer to that section for details. 

‘We recommend filling the extraneous row(s) or column(s) with zeros. 
Modifications 


None 


MatTrans 
Name: MatTrans 
‘Type: Procedure 
Purpose: To transpose a matrix 
Calling Sequence: MHatTrans(tatrixA, Matr xB) 














Description 
MatTrans creates the transpose of a given matrix. The initial matrix and its transpose 
are two-dimensional, square, and the sume size. They contain values of type real, 
Input 
Matrix real Array containing the matrix to be transposed 


The following global const and type declarations must be specified in your main 
Program: 





const 
MatrixSize = 3, 


type 
MatrixType = arrayCt. tatrixSize, 1. HatrixSize) of real; 


‘The constant HatrixSize defines the size of the square arrays. (That is, the value 
offfatr ixSize is the number of elements on the main diagonal of your input matrix.) 
HatrixSize can be any positive integer. The value 3 is only an example. 


Output 
MatrixB real Array containing the transpose of MatrixA 
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Limitations and Error Conditions 
None 

Sample Usage 

Program SampleUsageOfMatTrans; 


const 
MatrixSize = 3; 





type 
MatrixType = arrayCt, MatrixSize, 1, MatrixSize] of real, 
var 
NatrixA, MatrixB - HatrixType; 
anid * integer; 


(SI MatTrans, PSL) 
(SI MatShow. PSL? 


‘BEGIN 
for I >= 1 to MatrixSize do 
for J = 1 to MatrixSize do 
MatrixACl, J] = 1 = J 
MatTrans(MatrixA, MatrixB), 
writeln(’ MatrixA ="), MatShow(MatrixA); 
uriteln(’ Transpose of Matrix ="), MatShou(MatrixB) 
END. 


Running this test program produces the following output: 





Matrix = 
0.00 8-100 +208 
1.08 808 = -1.80 
208 1.00 0.00 
Transpose of MatrixA = 
8.00 108 2.08 
“1.08 8.08 100 
2080-108 0.08 
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Subprogram Listing of MatTrans.PSL 





Variables 


1 Subscript pointing to the currently referenced row of 
Matrix® and the currently referenced column of MatrixB 


J ‘Subscript pointing to the currently referenced column of 
Matrix and the currently referenced row of Matr 1xB 
Discussion 


You can create the transpose of a nonsquare matrix with MatTrans by using the 
technique presented in the Discussion section of the HatAdd subprogram. Refer to 
that section for details. 


Modifications 


None 


Matinv 





Name: Matinw 
Type: Procedure 
Purpose: To invert a matrix 
Calling Sequence: HatInu(tatrixA, HatrixB, OK) 
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Description 
MatInv inverts a matrix, if possible. The matrix must be two-dimensional and square, 
and it must contain values of type real. 


Input 
Matrix real Array containing the matrix to be inverted 


‘The following global const and type declarations must be specified in your main 
program: 





const 
MatrixSize = 3; 


type 
MatrixType = arrayCt..tatrixSize, 1. MatrixSize of real, 


‘The constant MatrixSize defines the size of the square arrays, (That is, the value 
of MatrixSize is the number of elements on the main diagonal of the matrix to 
be inverted.) HatrixSize can be any positive integer. The value 3 is only an example. 


Output 
MatrixB real Array containing the inverse of Matr ixA 
1 boolean Result of the procedure. If OK is true, the inversion 
was successful; if OK is false, the inversion was 
unsuccessful 


Limitations and Error Conditions 


‘Matrix inversion cannot be accomplished if the matrix is singular (has a determinant 
equal to zero). In such cases, the procedure terminates with OK set to false. The 
values in the array Matr {xB are indeterminate 


‘The algorithm tests whether certain computational values have become zero. Be- 
‘cause of round-off and truncation errors, however, a certain tolerance away from 
zero must be allowed in these values. The constant ErrorBound defines this toler- 
ance limit. You should sct it to a value about 10 orders of magnitude (Turbo's 
real-number precision) smaller than the absolute value of typical numbers in your 
input matrix. ErrorBound’s current setting is appropriate for matrix elements of 
order unity. If your application uses much larger or much smaller numbers, adjust 
ErrarBound as explained in the Modification section. 


338 ‘TURBO PASCAL PROGRAM LIBRARY 





Sample Usage 
Program Sampl@UsageOfMat Inu; 


const 
MatrixSize = 3; 


type 
HatrixType = arrayCt. MatrixSize, 1. MatrixSize) of real; 


var 


iJ integer; 
Matrix, MatrixB © MatrixType; 
OK boolean; 

CSI Matiny, PSL) 

($1 MatShow, PSL) 

BEGIN 


MatrixACt, 1] °* 3, MatrixACl, 2] := 5; MatrixACt,3] <= -1, 
MatrixAC2, 1] ©= 1, MatrixAC2,2] «= 4; MatrinAC2, 3] <= -8.7, 
MatrixACS, 1] :* 2, MatrixACS,2] °= 5; MatrinAC3,3] <= -t, 
writeln(’ Input Matrix =’); MatShow(MatrixA); 





Matinu(MatrixA, MatrixB, OK); 
1f OK then 
begin 
uriteln( Inverted Matrix =); MatShou(Matr1 xB) 
end 
else 


uriteln(’Matrix is singular’) 
END. 


Running this test program produces the following output: 





Input Matrix = 
3.08 Seo -1.00 
1.08 400 = -8.78 
200 500-100 
Inverted Matrix = 
100 60-108 
2.80 200 «-228 


608 1608 14.08 
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Subprogram Listing of Matinv.PSL 
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Variables 
ErrorBound Maximum allowable deviation of a value from zero 
(needed because of round-off and truncation errors) 
1K M ‘Subscripts in the two-dimensional arrays 
Factor Multiplicative factor applied to a row of MatrixA and a 
row of MatrixB 
Temp ‘Temporary value of an array element 
Discussion 


‘The inverse of a matrix is, in effect, the “reciprocal” of that matrix. Matrix division 
‘can thus be accomplished. Instead of dividing one matrix by another, you multiply 
‘one matrix by the inverse of the other. It follows that multiplying a matrix by its 
‘own inverse will result in a unity matrix. A unity matrix has ones on its main diagonal 
‘and zeros everywhere else. Any square matrix multiplied by the unity matrix (of 
the same size) simply results in the original matrix. 

A matrix is singular (and thus cannot be inverted) if one of its rows (or columns) 
consists of all zeros or if one of its rows (or columns) is an exact multiple of 
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another. In these cases, Mat Inv will terminate and set the boolean flag OK to false. 


Be careful not to assume anything about the values in the MatrixB array in such 
cases, The values are indeterminate. 


Modification 


ErrorBound must be adjusted if your input array contains elements much different 
from order unity. This adjustment is discussed in the Limitations and Error Con- 
ditions section. You may set ErrorBound to any real number greater than zero, If 
you set ErrorBound to zero, you will likely cause the procedure to terminate un- 
‘successfully (OK = false) for most practical cases 


Determ 





Name: Determ 
Type: real function 
Purpose: To evaluate the determinant of a matrix 
Calling Sequence: Detern(HatrixA) 











Description 
Determ calculates the determinant of a two-dimensional square matrix, Matrix ele 
ments are of type real, and the result is also of type real. 

Input 


Matrix real Array containing the matrix for which the 
determinant is to be evaluated 


‘The following global const and type declarations must be specified in your main 
program: 





const 
MatrixSize = 3; 


type 

HatrixType = array(1..tatrixSize, 1 MatrixSize] of real, 
‘The constant MatrixSize defines the size of the square array. (In other words, the 
value of Hatr ixSize is the number of clements on the main diagonal of Matr’xA.) 
MatrixSize can be any positive integer. The value 3 is only an example. 
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Output 


Determ real The function Deter 
Matrix, 


returns the determinant of 





Limitations and Error Conditions 


Determ contains an embedded recursive procedure named Dolt, As MatrixSize 
increases, computational time and memory use rise dramatically because of the 
recursion. For matrices with nonzero clements, table 12.1 shows typical compu- 
tation times on a standard IBM PC. 








Table 12.1 
Execution Speed of Determ 


MatrixSize Approximate Time 


(in Seconds) 
4 or less Less than 1 
5 1 
6 4 
7 24 
8 190 
9 oF more 1100 or more 





Overflow or underflow can occur if your matrix elements are several orders of 
magnitude larger or smaller than 1, especially when MatrixSize is greater than 5, 
Underflow can occur also when individual matrix elements differ greatly from each 
other in order of magnitude. Determ does no internal checking for these possibilities. 





Sample Usage 
Program SampleUsage(fDeterm, 


const 
MatrixSize = 3, 





type 
HatrixType = arraylt. MatrixSize, 1. MatrixSizel of rea! 
var 
Matrix © MatriaType; 
1 J = integer; 


Value + real; 


MATHEMATICS AND ENGINEERING 343, 





(SI Determ PSL) 
($1 MatShow, PSL) 


‘BEGIN 
for I i= 1 to MatrixSize do 
for J <= 1 to MatrixSize do 

MatrixACI, JJ s* 1 + J; 
MatrixACt, 2] <= 1.8; 
writeln(’ Matrix =); 
MatShow(MatrixA); 
Value «= Determ(MatrixA); 
writeln (Determinant of Matrix =", Ualue:6:2) 





Running this test program produces the following output: 





Matrix = 
200 1.60 4.00 
3.00 4.08 5.08 
4.08 5.08 6.08 


Determinant of MatrixA = -2 48 


Subprogram Listing of Determ.PSL 





34d ‘TURBO PASCAL PROGRAM LIBRARY. 








Variables 
‘Variables for the Function Detera 
ValDeterm Current (temporary) value of the determinant 
J Index variable 
Done boolean array indicating completion of evaluation at 
level J 
‘Variables for the Embedded Recursive Procedure Dolt 
Term Next term in ValDetera calculation 


Sign Sign (+ or -) for next Term in ValDeterm 


MATHEMATICS AND ENGINEERING 345 





N Number of term being computed 

" Offset to N 

KJ Indices into MatrixA array 
Discussion 


Most algorithms to calculate determinants depend on triangulating the original 
matrix (reducing it to a form with all zeros on one side of the main diagonal). 
This process requires row and column manipulation as well as scaling, For best 
‘mathematical precision, the appropriate pivot clement must be searched for at each 
step of the calculation before the critical divisions and multiplications are per: 
formed. All this activity typically requires quite lengthy program code. 

Deter, however, calculates the determinant by implementing the combinatorial 
definition of a determinant. The resultant recursive code is more elegant but often 
takes longer to run than the code from a typical triangulation scheme. 





Modifications 
None 
Inte 
Name: Integral 
Type: Procedure 


Purpose: To evaluate a definite integral of a given function 
Calling Sequence: Integral (LouX, HighX, Result, Code) 








Description 
Integral calculates a numerical approximation of a definite integral, using Simp- 
son's rule. You provide the function to be integrated and the upper and lower 
bounds of the integration domain. You can also specify the accuracy of the solution, 


Input 
Louk real Lower integration limit 
HighX real Upper integration limit 
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‘The integration domain is considered to range in X from X = LouX to X = Hi ghk 
But there is no restriction that HighX be greater than LouX. In fact, HighX can be 
greater than, smaller than, or equal to LouX. 

‘You must provide the function to be integrated. It is called HyFune and should be 
specified in your main program as 


function MyFune(X: real): real; 


When called with a value for X, MyFune must return the value of your function at 
that X. HyFune can be as simple or as complicated as you require. It can be a one- 
line formula or a table (with a routine to interpolate between discretely specified 
values). What matters is that the function be continuous over the integration do- 
main, For our purposes, this means that MyFunc returns a finite real value for any 
X in the integration domain. 


‘The integral is the “area under the curve." This is the shaded area shown in fig- 
ure 12.1 


YatvFunc) 


Low HiGHX 
Fig. 12.1. The integral of MyFune from Louk to Highk 


Output 
Result real Value of the integral 
Code real Accuracy of the solution. (See Limitations and Error 


Conditions.) 
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Limitations and Error Conditions 


Integral works by dividing the integration domain into 2 number of subintervals, 
calculating the integral of each subinterval, and summing the results. The procedure 
then doubles the number of subintervals and recalculates the entire solution. This 
Process continues until two successive iterations are sufficiently close to each other 
(convergence) or until the number of subintervals reaches a specified maximum 
(nonconvergence). The variables MaxError and MaxNuaSegs control these conver: 
gence criteria. See the Modifications section for an explanation of how to adjust 
these variables. 


‘The real variable Code provides information about the accuracy of the solution, If 
Code is greater than zero, the solution converged, and Code is the number of sub- 
intervals used in the final calculation. If Code is less than zero, the iteration did 
not converge, and the absolute value of Code is the relative error between the last 
two approximations. In this case, the procedure still returns its best solution in 
the variable Result. Although the value is often acceptable for the integral, be careful 
using Result when Code is less than zero. 


Sample Usage 
program SampleUsageDf Integral; 


var 
Lox, HighX, Result, Code: real, 


function MyFune(X: real) real; (Mod, #3) 
begin 

MyFune «= 4.0/7 (1.0+K* x) (Mod, #3) 
end; 


($1 Integral. PSL) 


BEGIN 
Louk 
High 
Integral (Lou, HighX, Result, Code); 
if Code > 8.8 then 

uriteln(’ Value of integral =", Result) 
else 
writeln(’ Integral calculation did not converge’ ) 





=o 
$ 


END. 


Running this test program produces the following output: 


Value of integral = 3. 1415926530E+00 


Subprogram Listing of Integral.PSL 
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Variables 


MaxError 


J 

4 

NunSegs 

x 

Oldval 
Error 
Seguiidth 
CurrentSum 
Tenp 


Constant that determines the maximum number of 
subintervals allowed 


Constant equal to the maximum percentage error allowed 
between successive iterations: 


Loop index 

Number of terms in the summation loop 
‘Number of subintervals in the current iteration 
Current value of X (along the integration domain) 
Solution calculated by the last iteration 
Percentage error between the last two iterations 
Width of one subinterval 

Working total of terms during an iteration 
‘Temporary value of terms during an iteration 
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Discussion 

If your function consists of experimental data at discrete values of X, you must 
enable MyFune to calculate the function at intermediate values of X. We recommend 
‘one of two approaches. The first is to write the function to interpolate linearly (or 
in higher order) between the appropriate values of X. For this approach, you search 
your data table for the experimental X values that bound the value of X where the 
function is to be evaluated. The second method is to use the program PolyFit (see 
Chapter 18), which can produce an approximate polynomial expression to fit your 
experimental data. This expression can then be used in MyFunc. 


Be sure that you specify HyFune in your main program before the procedure 
Integral appears. MyFunc must be global to Integral 

Integral contains the embedded function Simpson, which calculates the value of 
the integral depending on the current value of NunSegs, After Simpson is invoked 
for each iteration, the percentage error between the last two iterates is computed, 
‘This is the absolute value of the difference between the two iterates divided by 
the last iterate. When this percentage error drops below MaxError, the procedure 
is considered to have converged to the desired solution. 


Modifications 


1, MaxNunSegs is the maximum number of subintervals allowed, The 
‘number of subintervals doubles with each iteration if convergence is not 
achieved. The algorithm terminates if MaxNunSegs is exceeded and 
convergence is still not achieved. You may change its value from 1008 10 
any positive integer. 


2, MaxError is the required percentage error for successful convergence. 
‘The algorithm terminates when MaxError is satisfied. You may change its 
value from 1, 8-6 to any positive real number. 


3. If you prefer to call your input function something other than MyFune, 
change its name in all the indicated lines. 


4. The number of subintervals used in the initial iteration is specified by 
NunSegs. You may want to raise its value from 1@ if you know that your 
case will require many more subintervals for successful convergence. 
NunSegs must be a positive even integer greater than or equal to 4. 
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Root 





Name: Root 
Type: Procedure 
Purpose: To calculate real roots of a given function 
Calling Sequence: Root (LouX, HighX, Result, OK) 








Description 


Root attempts to find a value of X so that HyFune(X) = 0, in which MyFune is any 
function of X that you provide. You specify the range of X over which the search 
takes place. You can optionally specify the accuracy of the solution and the res: 
olution of the search domain. 


Input 
Louk real The lower end of the search domain 
HighX real ‘The upper end of the search domain 


‘The search domain is considered to range in X from X = Louk to X = HighX But 
there is no restriction that HighX be greater than LowX. The algorithm works cor- 
rectly if HighX is greater than, equal to, of less than Lou. 


‘You must provide the function HyFune. Specify it in your main program as 


function MyFune(X: real): real; 


When invoked with a value for X, MyFune returns the value of the function at 
that X. HyFunc can be as simple or as complicated as you require. It can be a one. 
line formula of a table (with a routine to interpolate between discretely specified 
values), What matters is that the function be continuous over the search domain, 
For our purposes, this means that MyFune returns a finite real value for any X in 
the search domain. 
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Output 
Result real ‘The value of X for which MyFune(X) = 0 
« boolean The outcome of the procedure. If OK is true, a root 


‘was found; if OK is false, no root was found. 
If OK is false, the value of Result is meaningless. 


Limitations and Error Conditions 


Root works by trying to find a bounded interval in which a root occurs. The pro- 
‘cedure first checks whether MyFunc(LouX) and MyFune(Hi ghX) have opposite signs, 
If the signs are opposite, a root occurs at some X in this search domain, Otherwise, 
Root continually divides the search interval into smaller and smaller subintervals, 
looking for one bounding a root. This partitioning process continues until the num- 
ber of segments (subintervals) becomes larger than the constant NaxNuaSegs, If 
tMaxNunSegs is too small, the algorithm may terminate unsuccessfully even though 
4 root theoretically exists. See the Modifications section for an explanation of how 
to adjust MaxNunSegs, 

‘Once the search interval is bounded, Root iterates until the solution is found to a 
tolerance of less than the constant MaxError. More specifically, X is a solution when 
the absolute value of HyFune(X) is less than HaxError. See the Modifications section 
for information about adjusting MaxError. 


‘The boolean flag OK reveals the outcome of the procedure. When OK is true, a 
successful root is contained in the variable Result. When OK is filse, no root was 
found, Be sure to test OK after calling Root, because Result is meaningless if OK is 
false. 


Sometimes multiple roots exist. Root cannot detect this condition and terminates 
successfully once any root is found. If you find a root but suspect that another one 
exists, try the following technique. Invoke Root twice more. First, leave LouX un- 
changed but set Hi ghX just below the found root. Second, set LouX just above the 
found root but leave HighX at its original value. (For this technique, it is assumed 
that the original LouX is less than the original Hi ghX.) 
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Sample Usage 
Program SampleUsageOfRoot; 


var LouX, HighX, Result = real; 
OK © boolean; 


function MyFune(X: real)* real; (od, #3) 


begin 
HyFune <= sin(X) (Hod, #3) 
end; 


($1 Root. PSL) 


‘BEGIN 
LowX <= 1.0; 
Highk =* 5.0; 
Root(LouX, HighX, Result, OK); 
1f OK then 
writeln(’ Root **, Result) 
el: 





‘iteln(’No root found’ ) 





Running this test program produces the following output: 


Root = 3. 14159202586+80 


Subprogram Listing of Root.PSL 








@ 
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Variables 
MaxNunSegs 


MaxError 
x 

Lo 

wat 

Flo 

FH 
Width 
Test 


NunSegs 


Constant equal to the maximum number of subintervals 
allowed to bound a solution 


Constant equal to the error tolerance allowed in a solution 
Current value of X in the search domain 

Lower X boundary on the current subinterval 

Higher X boundary on the current subinterval 
Value of HyFune (Xo) 

Value of MyFunc(XH1) 

Length in X of a specific subinterval 

Value of MyFune(X) for the current 

Loop index 

Number of subintervals in the current partitioning 
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Discussion 
If your function consists of data at discrete values of X, the comments in the Dis- 
cussion section of the Integral subprogram pertain here also. 


Be sure that you specify MyFune in your main program before the procedure Root 
appears. HyFune must be global to Root. 


Root contains the embedded procedure Iterate. This procedure homes in on the 
correct solution once the search domain has been bounded. Iterate works by 
continually bisecting the search domain and retaining the half interval that still 
contains the root. The process is repeated until the root is obtained to the required 
accuracy. Although Iterate is a zero-order method, and thus relatively slow com: 
Pared to higher-order techniques, it works for any continuous function, Higher- 
order methods converge faster for most practical cases but can be slow for certain 
pathological ones. One higher-order method is detailed in the Modifications section, 


Modifications 


1, MaxNurSags is the maximum number of subintervals allowed in the 
search for a bounded solution domain. The width of each subinteryal is 
continually halved until a solution domain is found. If you increase 
NaxNunSegs, the procedure will have increased resolution in its attempt 
to find a solution domain. If one cannot be found, the cost is additional 
‘computation time, 


2, NaxError specifies the solution criterion by requiring that 
abs(MyFunc(X)) ¢MaxError for X is a satisfactory solution. You may 
change HexError from 1. @-6 to any positive real number. 

3. If you prefer to call your input function something other than MyFunc, 
change its name in all the indicated lines. 

4. A higher-order convergence formula can be used for X. Try the 
following replacement for the entire line: 

X == (FHL © Wo - Flo * XHi) / (FHI - Flo), 
‘This formula converges faster for most practical functions but can be 
slower in certain pathological cases. 


MATHEMATICS AND ENGINEERING 387 





Deriv 





Name: Deriv 
Type: Procedure 
Purpose: To calculate the derivative of a given function 
Calling Sequence: Deriv(¥Ual, Result, 0X) 











Description 


Deriv calculates 2 numerical approximation of the derivative of HyFune at ¥Val, 
which is a given value of the independent variable. HyFune is a function of X that 
you provide. You can also specify the desired accuracy of the numerical solution, 


Input 


Val real ‘The value of X at which the derivative is to be 
calculated 


You must provide the function MyFune. Specify it in your main program as 


function MyFunc(X: real): real; 


When invoked with a value for X, HyFune returns the value of your function at that 
X. MyFune can be as simple or as complicated as you require. It can be a one-line 
formula or a bivariate table (with a routine to interpolate between discretely speci- 
fied values), What matters is that the function be continuous near XVal. See the 
Limitations and Error Conditions section for more details. 


Output 
Result real The derivative of MyFune at XVal 
ox boolean Outcome of the procedure. If OK is true, a solution 


was found, if OK is false, no solution was found. 
If OK is false, the value in Result may still be a reasonable approximation of the 
desired derivative. See the Limitations and Error Conditions section. 
Limitations and Error Conditions 


Deriv calculates the derivative by using a forward.differencing technique. MyFune 
is evaluated for values of X in the range XVal <= X <= (¥Val + 2Delta), Delta is 
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set to 0.01 initially. This setting is reasonable if your function is to be evaluated 
with X approximately of order unity. If your typical X values are several orders of 
magnitude higher or lower than 1, you may want to change Delta appropriately 
‘as explained in the Modifications section. 


If your function is not well behaved for X > XVal, you may want to use a backward- 
differencing technique to evaluate the derivative. For instance, you would use such 
a technique if MyFunc is not defined for X > MVal. Again, see the Modifications 
section, 


Deriv iterates by continually halving Delta. This process continues until the per- 
centage change in the derivative becomes less than MaxError. If the iteration does 
‘not converge in MaxNuaTr ies, the procedure returns with OK set to false, But Result 
still contains the last iterate to the derivative. This last iterate may cautiously be 
used as an approximate solution. The control variables MaxError and NaxNuaTr ies 
can be adjusted. See the Modifications section. 








Sample Usage 
Program Samp|eUsageOfDer iv; 


var XVal, Result « real; 
1K boolean, 


function MyFunc(X: real): real, (Hod. #3) 


begin 
MyFune = sin(x) (tod, #3) 
end; 


($1 Dertv, PSL 


BEGIN 
Wal == 8.0; 
Deriv(Xval, Result, OK); 
if OK then 
uriteln(’ Derivative ", Result,’ at X=", Xyal:6:2) 
else 
uriteln(’ Error’ ) 
END, 


Running this test program produces the following output: 


Derivatii 1 eoe@@e1382E+@8 at X= 80 


Subprogram Listing of Deriv.PSL 








360 ‘TURBO PASCAL PROGRAM LIBRARY 
Variables 
MexNuaTries Constant equal to the maximum number of iterations 
allowed 
MaxError Constant equal to the maximum percentage error allowed 
for convergence 
InitialDelta Initial value of Delta 
Delta ‘The current step size for X used in the difference equation 
FPrine ‘The value of the derivative at the current iterate 
OLdFPr ine ‘The value of the derivative at the last iterate 
FL MyFune (Val) 
F2 MyFune (Val + Del ta) 
F3 MyFune (Val + 2Delta) 
Error Percentage error between the last two iterates 
NuoTries Number of iterations already completed 
Discussion 


If your function consists of data at discrete values of X, the comments in the Dis- 
cussion section of the Integral subprogram pertain here also, 


Be sure that you specify MyFune in your main program before the procedure Der iv 
appears. MyFune must be global to Dery. 

To approximate the derivative, Deriv uses a second-order (quadratic) difference 
‘equation. MyFune is evaluated at three points (Val, Val +Del ta, and XVal+2Delta) 
in cach iteration. This method is quite accurate for a wide range of functions if 
Delta is picked appropriately. The algorithm adjusts Delta by continually halving 
it until convergence is achieved. 


MATHEMATICS AND ENGINEERING 361 





Modifications 


1. If your case is not converging, allow the procedure more iterations by 
raising the value of MaxNunTr les. Its value can be any positive integer. 


2. MaxError specifies the maximum allowable percentage error between 
‘two iterates for successful convergence. You may change the value of 
NaxError from 1.0E-6 to any positive real number, 


3. If you prefer to call your input function something other than MyFunc, 
change its name in all the indicated lines. 


4, InitialDelta is the value of Delta in the first iteration. The variable’s 
value of 0.01 assumes that the difference between MyFunc (Delta) and 
MyFunc(Delta + @. 81) is reasonable. Reasonable here means something 
large enough to be recognized within Turbo’s real-number precision but 
smaller than several orders of magnitude. You may (rarely) need to 
make InitialDelta larger or smaller to achieve a reasonable difference. 
InitialDelta must be a positive real number. 


5. You may want to try a backward-differencing technique if your function 
is not defined or not well behaved for X > *Val. Change the line 
indicated by (Hod. #5) to 


Delta :* - InitialDelta; 


Even for well-behaved functions, this technique can be a worthwhile 
redundancy check on the calculated derivative. Your answer should not 
change significantly. 


Diff—qn 





Name: DiffEqn 
‘Type: Procedure 
Purpose: To solve a specified differential equation 
Calling Sequence: DiffEgn(Xinitial, Yinitial, Xfinal, Yfinal, OK) 











Description 
You specify DYDX, the function of X and ¥ to be solved. DYDX must be a first-order, 


ordinary differential equation. X is the independent variable, and Y is the dependent 
variable. You must provide the initial values of X and Y and the final value of X. 
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‘The procedure calculates the final value of Y. You can specify also the desired 
‘accuracy of the numerical solution. 


Input 
Xinitial real The initial value of the independent variable 
Yinitial real The initial value of the dependent variable 
Xf inal real ‘The final value of the independent variable 


‘You must provide the differential equation through the function DYDK. Specify it in 
your main program as 


function DYDX(X, ¥* real): real; 


DYDX returns the value of the differential equation when invoked with values for X 
and/or Y. DYDX should be continuous over the range of X and Y expected in the 
computation. For our purposes, this means that DYDX will return a finite real value 
for any X and Y occurring in the calculation. 


Output 
Yfinal real The value of Y at Xf nal 
oK boolean Result of the procedure. If OK is true, a solution was 


found; if OK is false, no solution was found. 


If OK is false, the value of YF inal may still be a reasonable approximation of the 
desired answer, See the Limitations and Error Conditions section. 


Limitations and Error Conditions 


DiffEgn iterates by continually doubling NusSegs, the number of segments in the 
X domain. The value of Yf inal is progressively updated while each iteration im- 
Proves the numerical accuracy (unless round-off errors dominate), This process 
continues until the percentage change in YFinal is less than HaxError. If the it- 
eration does not converge before NunSegs reaches MaxNunSegs, the procedure re- 
turns with OK set to false. However, Yfinal still contains the last (best) iterated 
value. This last iterate may cautiously be used as a good approximation of the desired 
solution. The control variables MaxError and NaxNuaSegs can be adjusted. See the 
Modifications section. 
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Sample Usage 
Program SampleUsageOfDi Ean, 


real; 


var 
Xinitial, Yinitial, Xfinal, Yfinal” 
7 boolean; 





function DYDK(x, Y: real): real; (od. #3) 


begin 
DYDX == Y * sin(x) od, 


end; 
(SI DiffEgn, PSL) 


‘BEGIN: 
initial «= 0.2, 
Yinitial = 1.0; 
Xfinal = 1.8; 
DIffEgn(Xinitial, Yinitial, Xfinal, Yfinal, OK); 
if 


writeln(’ Yfinal =, Yfinal, ‘ at Xfinal =", Xfinal) 


else 
writeln(’ Error’) 


Running this test program produces the following output: 


Yfinal = 1. S835951659E+00 at Xfinal = 1, e@@@@00000E+00 


Subprogram Listing for DiffEqn.PSL 
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Variables 
MaxNunSegs 


MaxError 


xl 

* 

vl 

YF 
Yprevious 
Utdth 
Ha fl 
Error 
KA, KB 
kc, KD 
J 
NunSegs 


Discussion 


Constant used to determine the maximum number of 
segments allowed in the X domain 


Constant equal to the maximum percentage error allowed 
for convergence 

Initial X in the current working segment 
Final X in the current working segment 
Initial Y in the current working segment 
Final Y in the current working segment 
Final Y in the previous working segment 
Length (in X) of the current working segment 
Half of Width 

Percentage error between the last two iterates 
Runge-Kutta coefficients: 

Runge-Kutta coefficients 

Loop index 

Number of segments in the current iteration 


Solving differential equations is often necessary in practical engineering problems, 
Fe esce ae sei (exams sain rcp a 


is obtainable. 


;, however, such a solution is not possible. Then you must 


solve the equation numerically, using computer software like Di ffEgn. 
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Dif fEgn uses the fourth-order, Runge-Kutta method to solve your differential equa- 
tion. The Runge-Kutta technique is explained in detail in many numerical analysis 
books, 

You may want to produce a table of X and Y pairs instead of just the final values, 
Such a table is needed to draw a smooth graph of the solution curve while X varies 
from Xinitial to Xfinal. To create the table, place a loop in your main program 
where DiffEgn is invoked. Set the first value of Xfinal to be the first value you 
want in your table. Make the call to DIffEgn. Then reset Xinitial to your last 
Xfinal, and Yinitial to your last ¥final, Reset Xfinal to be the next value you 
‘want in your table. Invoke Dif fEgn again and continue the process until Xf inal 
feaches your true final value. This technique can produce a table of any resolution 
you want. 

By the way, Xf inal does not have to be larger than Xinitial. This procedure works 


fine if X is decreasing, The procedure works fine also if Xfinal equals Xinitial, 
although Yf inal will simply equal Yinitial in this case 





Modifications 


1. If your case is not converging, allow the procedure more iterations by 
raising the value of MaxNuaSegs. It can be any positive integer greater 
than 1 


2, MaxError specifies the maximum allowable percentage error between 
two iterates for successful convergence. HaxError can be any positive 
real number. 


3. If you prefer to call your input differential equation something other 
than DYDX, change its name in all the indicated lines. 


13 





Statistics and Probability 





Although often maligned in the popular press (“There are three kinds of lies: lies, 
damned lies, and statistics"), the science of statistics provides valuable tools for 
data analysis, In this chapter are nine subprograms drawn from a variety of useful 
subjects in statistics and probability. 

Stats provides elemental statistical analysis of a set of real numbers. The subpro: 
gram computes the mean, the standard deviation, and other basic statistical 
quantities. 





Permutations and combinations of a collection of objects occur regularly in com- 
binatorial probability. NuPerm and NusComb make these calculations. As a bonus, 
NunPerm provides a way to calculate factorials of integer numbers, 


Probability distribution functions enable you to model a myriad of physical phe- 
nomena by quantitative analysis. BinomDis and NoraDis calculate the two most 
important cases: binomial distributions in the discrete case, and normal distributions 
in the continuous case 


‘The subprogram RndNorm provides random numbers drawn from a specified normal 
distribution. This subprogram complements Turbo's random function, which pro- 
vides random numbers drawn from a uniform distribution, 


Paired X-Y data often results from experiments and from data collected in surveys. 
LinReg calculates correlation coefficients, which provide a measure of how well 
the data fits on a straight line. 


‘The chi-square test has far-reaching applications in several areas. It provides a quan- 
titative means of testing experimental hypotheses. GetChiSy computes the value of 
the chi-square statistic for a given experiment. ChiProb calculates the probability 
that a given range of chi-square will occur. Although few references provide a 
computational procedure for calculating the chi-square tables, ChiProb can do the 
calculation to any resolution you want. 


368 TURBO PASCAL PROGRAM LIBRARY 





Stats 





Name: Stats 
Type: Procedure 
Purpose: To calculate statistics for a set of discrete values 


Calling Sequence: Stats(Numrray, Count, Mean, Median, StanDev, 
MinUalue, MaxValue) 











Description 


‘You provide the data in the one-dimensional array Nunfrray. Stats then computes 
the mean, median, standard deviation, minimum value, and maximum value of your 
data. The data is assumed to be real. See the Modification section for an explanation 
of how to use integer instead. 


Input 
NunArray real Array of the data values 
Count Integer Number of data elements in NumArray to use in 


computing statistics 


The following global const and type declarations must be specified in your main 
program: 





const 
ArraySize = 250, 


type 
ArrayType = arrayCl. ArraySize] of real, 
‘The number 250 for the array size is just an example. Your array size can be any 
positive integer. 


Output 
Mean real Mean of the values in Numrray 
Median real Median of the values in Nunrray 
StanDev real Standard! deviation of the values in NunArray 
MinValue real Minimum value in Nunrray 


MaxValue real Maximum value in NumArray 
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Limitations and Error Conditions 


If Count is less than 1, the procedure is bypassed. No error message is displayed, 
and the results returned for the statistics are meaningless. The same is true if Count 
is greater than ArraySize. In this case, irrelevant calculations are done, and the 
results are again meaningless. Your responsibility is to be sure that Count is set 
accurately. 

If Count is 1, Stats returns a value of zero for the standard deviation, All of the 
other statistics have the value of NuafrrayC1I, If Count has a positive value less 
than ArraySize, statistics are computed for the first Count elements in Nunfrray, 


Sample Usage 


program SamplaUsaga0fStats; 


const 
ArraySize = 250, 








type 
ArrayType * arrayC1.frraySize) of real, (Hod. #1) 
var 
Nunfirray ArrayType; 
Count int 
Maan, Median, StanDev, MinUalue, MaxValue = real, 
(SI Stats, PSL) 
BEGIN 


NumArrayC1] =* 4.2, NunArrayC2] = 4 
NumArrayC4] <= 0.8, Nuefwray(S) = 5.4, 
Count 


9% NuwArrayC3) '= -3.3; 
NumPrray(6] = 2.6; 





6 


Stats(NumArray, Count, Mean, Median, StanDev, 


MinUalue, MaxValue); 





writeln(’ Number of Values =", Count 3); 
uriteln( Minimum Value =", Minvalue:8:4), 
uriteln(’ Maximum Value =’, MaxValue:6:4); 


uriteln( Hean =) Mean:8:4), 
writeln(’ Hedian =) Hedian:8:4); 
uriteln(’Std, deviation ~, StanDev:8:4) 


END. 
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Running this test program produces the following output: 


Number of values 
Minimum value 
Haximum value 
ean 


Median 
Std. deviation 


Subprogram Listing of Stats.PSL 
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Variables 

a Looping index 

K Subscript in sorting algorithm 

mid Half of Count when Count is even 

Temp Element of NusArray being sorted 

Valuesun ‘Sum of the first Count elements of Nusfrray 

SquareSum Sum of the squares of the first Count elements of NumArray 
Discussion 


Stats computes statistical parameters that describe a group of data. In statistical 
terminology the values in Nuafrray make up a “population sample,” They can be 
drawn from almost any sample group—for example, heights or weights of people, 
piston diameters from a manufacturing facility, or combustion times from a chemical 
‘experiment. 

|A primary measure of the data is its central tendency—one number that in some 
‘way represents the data or is typical of it. The most common of such measures is 
the mean, more correctly called the arithmetic mean and usually called the average. 
‘The mean is the sum of the data values divided by the number of values. Another 
description of central tendency is the median. It is the midpoint between the num- 
ber of data values. That is, half of the data values are larger and half are smaller 
than the median. For an odd number of values, the median is the middle value 
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when the data is sorted in numeric order. For an even number of values, the median 
is the number halfway between the two middle values. 


Another measure of the data is its variation, or dispersion. This measure indicates 
how closely the data tends to be dispersed around the mean. The standard deviation 
is computed by first summing the squares of each data value subtracted from the 
mean. This sum is then divided by the number of data values - 1. The calculation 
Produces the variance of the sample. The standard deviation is simply the square 
root of the variance. When the standard deviation is small, the data tends to be 
clustered close to the mean. When the standard deviation is large, the data tends 
to be spread farther from the mean. 


Stats also returns the minimum and maximum values of the sample. So that these 
values can be found and the median computed, the data is first sorted with the 
algorithm presented in the subprogram Sor tSIR. In Stats, however, the subprogram 
does not change Numfrray in the main program. The data in NumArray is in the 
same order before and after the call to Stats is made. Only the local copy of 
NumArray in Stats is modified 


Modification 


‘To compute statistics on an integer array, change the word real to integer in 
the indicated lines. The data in NunArray is then assumed to be integer, of course. 
‘The statistical quantities computed by Stats remain of type real. 





NumPerm 
Name: NumPerm 
‘Type: integer function 
Purpose: To calculate the number of permutations 
Calling Sequence: NusPerm(NuaThings, NunTake) 














Description 
NusPerm calculates the number of permutations of a specified number of objects 


taken a specified number of times. The result is of type integer. The Modification 
section provides an explanation of how to change the result to type real 
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Input 
NusThings integer Number of objects available 


NunTake integer Number to take 





Output 


NunPerm integer The function NusPera returns the number of 
permutations of NuaThings taken NuaTake at a time. 


Limitations and Error Conditions 
NunPerm returns a value of zero if the input conditions are not sensible. A sensible 
‘case must have NuaThings >= 1, NunTake >= 1, and NuaThings >= NuaTake. 
If NunThings is greater than 7, integer overflow is possible depending on the value 
‘of NunTake. See the Modification section. 





Sample Usage 
program Samp] eUsageOfNuaPerm, 
var 
NumThings, NumTake, J = integer, 
‘Answer Integer; (Mod, #1) 
($1 NumPerm. PSL) 
BEGIN 
writeln(’® Things’ -15, '# To Take’ 19, “# Permutations’ +24), 
NumThings == 6; 
for NumTake «= 1 to NumThings do 


begin 
Answer := NumPerm(NuaThings, NuaTake); 
writeln(NuaThings:18, NuaTake:21, Answer=21) 
end 
END. 
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Running this test program produces the following output: 


‘# Things To Take # Permutations 

é 4 6 

2 we 

6 3 128 

6 4 8 

6 5 728 

6 6 728 
Subprogram Listing of NumPerm.PSL 





Variables 
Result Accumulating value of the number of permutations 
J Looping variable 


Limit Lower limit of loop 
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Discussion 
‘The need for permutation calculations arises regularly in statistical analyses, par- 
ticularly discrete probability computations. The number of permutations of a col- 
lection of objects is the number of different arrangements you can make of those 
objects. Consider three billiard balls labeled 1, 2, and 3. lf you were to place them 
in a straight line, you could do so in six different ways: 123, 132, 213, 231, 312, 
and 321. Thus, there are six permutations of three objects. 


More generally, you can ask how many permutations exist if you take only so many 
‘objects at a time from your collection. For example, from four billiard balls labeled 
1 through 4, you can generate 12 permutations of the balls taken two at a time: 
12, 13, 14, 21, 23, 24, 31, 32, 34, 41, 42, and 43. 


NumPerm can be used to compute factorials. The number of permutations of n objects 
taken n at a time is simply n factorial. To calculate the factorial of a positive integer, 
therefore, you set both NuaThings and NusTake equal to the desired factorial, and 
NunPerm returns the answer. 


Modification 


Integer overflow is threatened whenever NusThings is greater than 7. You can 
‘circumvent this overflow by having the function do real arithmetic and return a 
real result. Change the type declaration integer to real in the designated lines. 
In the function declaration, change only the last occurrence of integer. Afterward, 
the line should appear as 


function NumPerm(NunThings, NuaTake: inte 





NumComb 
Name: NumComb 
‘Type: integer function 
Purpose: To calculate the number of combinations 
Calling Sequence: NumConb(NuaThings, NunTake) 














Description 


NunComb calculates the number of combinations of a specified number of objects 
taken a specified number of times. The result is of type integer. See the Modification 
section for information about changing the result to type real 
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Input 
NunThings Number of objects available 
NunTake ‘Number to take 

Output 


‘NumComb integer The function NumComb returns the number of 
combinations of NumThings taken NumTake at a time. 
Limitations and Error Conditions 


NunComb returns a value of zero if the input conditions are not sensible. A sensible 
case must have NuaThings >= 1, NuaTake >= 1, and NuaThings >= NunTake, 


IfNunThings is greater than 10, integer overflow is possible depending on the value 
of NuaTake. See the Modification section. 





Sample Usage 
rogram Samp|oUsage0fNuaConb, 
var 
NumThings, NumTake, J = integer; 
Answer integer; (Mod. #1) 
($1 NumComb. PSL) 
‘BEGIN 


writaln(’# Things’ <15, “® To Take’ <19, ‘# Combinations’ :24), 
NunThings <= 6, 
for NunTake == 1 to NuaThings do 
begin 
Answer ‘= NumComb(NumThings, NuaTake); 
writeln(NunThings:10, NuaTake:21, Answer :21) 
end 


END 
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Running this test program produces the following output: 


# Things To Take ® Combinations 
6 1 6 
15 
2 
15 
6 
a 


DARKO 
onaeon 


Subprogram Listing of NumComb.PSL 
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Variables 
Result Accumulating yalue of the number of combinations 
J Looping variable 
Limit Lower limit of loop 

Discussion 


Like permutation calculations, the calculation of combinations arises in discrete 
probability computations. A combination is a distinct subset of a group of objects 
without regard to order. A particular combination contains specific items, but there 
is no differentiation between the various ways these items can be arranged. 


Consider the example used in the discussion of permutations. You had four billiard 
balls labeled 1 through 4. There were 12 permutations of them taken two at a 
time. But there are only 6 combinations of them taken two at a time: balls 1 and 
2, (without respect to order), I and 3, 1 and 4, 2 and 3, 2 and 4, and 3 and 4, If 
you specify the total number of items and the particular number to take, the number 
of combinations is always less than or equal to the number of permutations 


‘We use a small trick in this subprogram to minimize the danger of integer overflow. 
If we have x number of objects and take them y at a time, the number of com. 
binations is the same as taking them (x - y) at a time instead. Therefore, NusComb 
checks which calculation results in the least chance of integer overflow. If overflow 
is indicated with no adjustment to NusTake, NunConb makes a recursive call to itself 
with NunTake adjusted. 





Modification 


Integer overflow is possible whenever NuaThings is greater than 10, You can cit- 
‘cumvent this overflow by having the function do real arithmetic and return a real 
result. Change the type declaration integer to real in the lines designated by 
(Mod, #1. Change only the last occurrence of integer in the function declaration, 
Afterward, that line should appear as 





function NuaComb(NuaThings, NuaTake: integer): real; 
In addition, change the line designated as (Hod. #1a) to 


Result '=Result /J 
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BinomDis 
Name: BinomDis 
Type: real function 
Purpose: To compute binomial distribution probabilities 
Calling Sequence: BinonDis(NusTrials, NuaHits, ProbHit) 














Description 
BinomDis calculates the probability of a given number of successes in a given number 
of independent trials according to the discrete binomial distribution, You must 
specify the chance of success in a single trial 





Input 
NunTrtals Number of trials 
NunHits Number of successes in NuaTr1als 
ProbHit Probability of success in a single trial 
Output 
BinoDis real The function BinoaDis returns the probability of 


exactly NumHits in NuaTr ial, 


Limitations and Error Conditions 


If the input is not sensible, BinoaD!s returns a negative probability of -1.0. All of 
the following conditions must be true for a case to be sensible: NunTr als must 
be at least 1, NunHits must be at least zero and no more than NuaTrials, and 
ProbHit must be at least zero and no more than 1 


As NunTrials increases, large factorials are computed by BinoaDis. Numeric over- 
flow can occur even though the subprogram is coded to avoid such overflow when- 
ever possible. The biggest danger occurs when NusHits is approximately half of 
NunTrials. If NuaTrials is less than 50, there is no problem. For larger values, 
NusHits must be closer to zero (or to NuaTrials) in order for BinoaD!s to avoid 


BinoaD!s returns a probability of exactly zero whenever the true result is less than 
1,0E-38. This zero probability occurs when Turbo's exp function is taxed by too 
large a negative number. BinoaDis treats such a result as zero instead of allowing 
a (presumably meaningless) overflow. See the Modification section. 
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Sample Usage 
program SampleUsageOfBinoaDis; 


var 
NunTrials, Nuits > integer; 
ProbHit, Result real; 


($1 BinomDis. PSL? 


BEGIN 
ProbHit == 8.25, 
NunTrials == 5; 


writeln(’ Probability of a hit in one trial =", ProbHit:6:3), 
uriteln; 
writeln(’ # Trials’ 10, ‘® Hits’ 13, ‘Probability’ « 
for NusHits «= @ to NuaTrials do 
begin 
Result <= BinomDis(NunTrials, NusHits, ProbHit); 
writeln(NumTrials:S, NusHits:15, Result:18:4) 
end 





END. 


Suppose that you randomly draw one card from a full pack (no jokers) of playing 
cards. Your chance of drawing a spade is 1 in 4. Now suppose that you repeat the 
selection 5 times (replacing the drawn card after each trial). The test program just 
presented computes the probability of achieving 0 through 5 hits (spades) in your 
experiment. The program produces the following output: 





Probability of a hit in one trial = 6.250 


Hits Probability 
r) @.2373 
1 8.3955 
2 8.2697 
3 2.0879 
4 8.2146 
5 2 0018 
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Subprogram Listing of BinomDis.PSL 
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Variables 
Factorials NunTrials! / NusHits! / ( ~ NusHits)! 
Temp ‘The natural log of the answer 
Seal ler ‘The smaller of NusHits and (NuaTr {als - NusHits) 
larg ‘The larger of NusHits and (NusTr ial's - NunHits) 
J Looping index 


Discussion 


Binomial distribution, which is a fundamental tool of discrete probability analysis, 
applies to any experiment in which each individual trial (or sample) has two distinct 
possible outcomes, These could be a hit or miss, a good item or a defective one, 
a head or tail, a success or failure, and so on. The binomial distribution gives the 
probability that a specific number of hits will be achieved with a certain number 
Of trials. All trials must be independent of each other so that the result of one trial 
cannot affect the result of any other trial. The probability of success in one trial 
‘must be known and must remain constant throughout the experiment. 


As indicated previously, BinoaDi aborts with numeric overflow if NuaTr tals is too 
large and NuaHi ts is not extreme. If you run cases in this range, you might consider 
using the Poisson distribution as an approximation of the binomial distribution. 
‘The bibliography contains references to some books that discuss using the Poisson 
distribution in this manner. 
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Modification 


You can eliminate the check for extremely small answers (less than 1.0E-38) by 
removing the lines indicated by (Mod. #1). You may want to remove these lines if 
you are working in a range in which extremely small probabilities are important. 
AAs discussed in the Limitations and Error Conditions section, overflow may occur 
if you make this change. 


NormDis 


Name: Normbis 
Type: Procedure 


Purpose: To evaluate frequencies and probabilities of a normal 
distribution function 


Calling Sequence: Norallis(Mean, StanDev, X, Frequency, Probability) 








Description 


You specify a particular normal distribution curve by giving its mean and standard 
deviation, NormDis computes the probability density function (that is, the frequency, 
or ordinate) and the cumulative distribution function (probability) at a given value 
‘of X (the abscissa). These quantities are shown in figure 13.1 
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Input 
Mean real 
StanDev real 
x real 
Output 


Frequency real 


Probability real 


Mean of the normal distribution 
Standard deviation of the normal distribution 
Abscissa value 


‘The probability density function (the ordinate) of the 
normal distribution evaluated at X 


‘The cumulative distribution function of the normal 
distribution function evaluated at X. This function 
specifies the probability that a random sample from 
the normal distribution has a value less than or equal 
tox 


Limitations and Error Conditions 


StanDev must be positive for any meaningful case. If StanDev is not positive, NormD{ s 
feturns the (impossible) value of -1.0 for both Freguency and Probability, 


‘The accuracy of the solution is controlled by MaxError. By adjusting MaxError, you 
can control the number of (correct) significant digits in the result. Of course, as 
resolution of the solution increases, the computation time increases also. See the 


Modifications section. 


Sample Usage 


program SampleUsageOfNoraDi s; 


var 


Mean, StanDev, X, Frequency, Probability = real; 


J 


($1 NormDis. PSL) 


* integer; 
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vuriteln; 
writeln(’X :3, ‘Frequency’ :28, ‘Probability’ 19); 
for J i= 5 to 11 do 
begin 
K+ 28.8% J, 
NoraDis(Mean, StanDev, X, Frequency, Probability); 
writeln (X:5-1, Frequency-18:7, Probability 18:7) 
end 


END. 


Running this test program produces the following output: 





Mean = 168.@ Standard Deviation = 28.0 


Frequency Probab! lity 
e 





Subprogram Listing of NormDis.PSL 
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Variables 

Variables for the Procedure NoraDis 

ye X transformed to a standard normal distribution variable: 
Z= (X- Mean) / StanDev 

MaxError Constant equal to the maximum percentage error allowed 
between successive iterations 

Arca Integral of the function NoraFune, from 0.5 to Z 

O1dval Area calculated by the previous iteration 

Error Percentage error between the last two iterations 

NunSegs ‘Number of subintervals in the current iteration 

Variables for the Embedded Function Siapson 

Segllidth Width of one subinterval 


CurrentSum Working total of terms during an iteration 
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Temp ‘Temporary value of terms during an iteration 
LocalZ ‘Current value of the abscissa in Z coordinates 
NumTerms Number of subintervals in the current iteration 
J Loop index 

Discussion 


‘The normal distribution is the most important continuous probability distribution, 
occurring regularly in both theoretical and applied statistics. The familiar bell. 
shaped curves describe a myriad of practical distributions, ranging from the weights 
of people to collision frequencies in a physics lab experiment. 

You can describe a particular normal distribution by giving its mean and standard 
deviation, With a simple change of variable, any normal distribution can be mapped 
into the standard normal distribution, having a mean of zero and a standard deviation 
of 1, NoraDts uses this technique. (Refer to any statistics text for additional details. 
‘The bibliography contains some references.) 


‘The probability calculation requires integrating this standardized curve. This is done 
by Simpson, an embedded iterative function that implements Simpson's rule. The 
‘embedded function NoraFunc defines the active part of the necessary function to 
be integrated. See the Integra! subprogram for a brief discussion of Simpson's rule, 


For a given normal distribution, the frequency is simply defined as the value of the 
ordinate corresponding to a given value of X. The frequency is symmetric about 
the mean. (That is, the frequency at X is the same as that at -X.) The probability 
is defined as the integral from minus infinity to X. When X equals the mean, the 
probability is 0.5. (It’s equally likely that a sample is greater than or less than the 
mean.) As X approaches plus infinity, the probability approaches 1 


Modifications 

1. MaxError is the percentage error required for successful convergence of 
the integration. This variable controls the accuracy of the output. The 
humber of correct significant digits in the result is approximately equal 
to the exponent in HaxError. Thus, when MaxError = 1.0E-6, there are 
approximately 6 correct digits. When MaxError = 1.0E-3, there are 
approximately 3 correct digits. You may change HaxError to any positive 
real number. 

2. NoraDis checks whether X is 13 or more standard deviations away from 
the mean. If so, NoraDis sets the frequency to zero and the area to one- 
half: Potential overflow in NoraFunc is therefore avoided. The adjustment 
should not cause any numeric inaccuracies because the normal 





STATISTICS AND PROBABILITY 389, 





distribution is essentially zero and unchanging past 5 or 6 standard 
deviations (and the distribution is seldom needed in that range for any 
practical work). Still, you may want to change the 13 to something 
smaller (say, 6) to speed up slightly the calculation in the unlikely event 
that you invoke NoraDis in this range. 


RndNorm 


Name: RndNorm 


Type: real function 
Purpose: To generate random numbers from a normal distribution 
Calling Sequence: RnéNorm(Mean, StanDev) 








Description 


RndNorm calculates a random normal deviate. This is a number randomly drawn 
from a normal distribution. You identify the specific normal distribution by giving 
the mean and the standard deviation. 


Input 
Mean real Mean of the normal distribution 
StanDev real Standard deviation of the normal distribution 
Output 
RndNorm = real ~The function Rndlorm returns a random number 
drawn from the normal distribution described by 
Hean and StanDev. 


Limitations and Error Conditions 


RndNorm returns results even for nonsensical values of the standard deviation. If 
StanDev is negative, the function returns the same random number produced by 
the absolute value of StanDev. If StanDev is zero, RndNorm returns the value of Mean 
each time. 


See modification 2 for the description of a rare potential error condition. 
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Sample Usage 
Program SampleUsageOfRndNorm; 


var 
Mean, StanDev : real; 
J integer; 


(SI RndNorm. PSL) 


BEGIN 
Mean ‘= 8.8; 
StanDov = 1.6, 
randomize; (Hod, #1) 
for J = 1 to 5 do 

writeln(RndNorm(Mean, StanDev) 18:4); 
wr iteln; 
for J == 1 to S do 
writeln(RndNora(1@8.8, 28.0)=10:4) 





This test program produces different numbers each time it is run. Because Turbo's 
random-number generator is used, the output changes from run to run. (See mod- 
ification 1 for further details.) The following output is typical 
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Subprogram Listing of RndNorm.PSL 





Variables 
Random A random number between -1 and +1 
RandomB Another random number between -1 and +1 
Radius? ‘The square of the distance hetween the point (Random, 
RandonB) and the origin (0, 0) 
Deviate Resultant random number. This number is drawn from the 
normal distribution with a mean of zero and a standard 
deviation of 1 
Discussion 


‘The need for random numbers drawn from a normal distribution arises frequently 
in computational statistics, especially in computer modeling and Monte Carlo simu- 
lation. (A Monte Carlo simulation is one that requires random numbers in a par- 
ticular probability distribution for part of the algorithm used.) Consider an actuarial 
life expectancy represented by a normal distribution with a mean of 70 (years) 
and a standard deviation of 10. A life insurance company might base its premiums 
‘on the results of a simulation, using RnéNora to generate sample death statistics 
RndNorm uses random numbers drawn from the continuous uniform distribution, 
(The numbers are supplied by Turbo’s builtin random function.) The algorithm 
depends on generating two such random numbers, each between -1 and +1. If you 
think of these numbers as X and Y coordinates, they define a point on a plane. The 
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algorithm needs this point to be on the unit circle; therefore, a new random point 
must be generated if Radius2 is greater than 1. The probability that Radius? is 
greater than 1 is (4-1)/m (about 27 percent of the time, by the way). A random 
point on the standard normal distribution can be generated by using the formula 
beginning with Deviate = from the subprogram. This algorithm, called the “polar 
‘method for normal deviates,” was developed by Box, Muller, and Marsaglia. (These 
applied mathematicians, especially Marsaglia, developed and refined many important 
‘numeric techniques to produce numbers from various distributions.) An excellent 
discussion of the algorithm and other methods of generating random deviates is 
contained in Section 3.4.1 in Knuth's book, The Art of Computer Programming, 
Volume 2. Refer to Knuth for a more complete explanation. 


A second normal deviate can be generated from the same pass through the sub- 
Program. If Random is replaced by RandoaB in the Deviate :* formula, a second 
deviate is generated, Even though the same Radius? is used for both calculations, 
both random deviates are independent of each other and normally distributed. Thus, 
if your application requires generating many random deviates, consider turning 
RndNorm into a procedure and passing both random deviates back to your main 
Program. This approach significantly saves computation time. 


Modifications 


1, You must be careful whenever you use Turbo Pascal's randomize 
Procedure. During testing, you may want to remove this statement. 
Removing it causes RndNorm to generate the same sequence of random 
Aumbers cach time the program is run, but only if you reboot Turbo 
between runs. For production runs, call randomize once, before any calls 
to random are made. Do not place randomize between successive rapid 
calls to random (such as inside RndNora itself). If you do, Turbo 
‘generates similar “random” numbers and destroys the validity of your 
results 

2, Theoretically, it is possible for Radius? to equal zero and thus cause a 
division by zero error. This possibility requires that random return two 
successive numbers exactly equal to 0.5 (to full computer accuracy) 
‘The odds against this are theoretically about 1 in 10 to the 22nd power, 
and probably zero, given Turbo’s pscudo-random-number generator. If 
you are paranoid about this possibility, change the indicated line to 

(Radius? ¢ 1.8) and (Radius2>@ 8); 


‘This formula causes a small increase in computation time. 
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LinReg 





‘Name: Linkeg 
‘Type: Procedure 
Purpose: To perform linear regression on a set of data pairs 


Calling Sequence: LinReg(Nun2Array, NumDataPairs, Intercept, Slope, 
CorrCoeff) 











Description 


Given a table of X-Y data pairs, LinReg finds the equation of the straight line that 
best represents the data. The method of least squares is used to calculate the slope 
and Y intercept of the line. The correlation coefficient is also computed. 


Input 
Nun2Array real A two-dimensional array representing the data. The 
first subscript identifies the ordinal number of the 
data pair. The second subscript is 1 when the array 
clement is an X value (independent variable), or 2 
when the array element is a Y value (dependent 
variable), 


NunDataPairsinteger Number of data pairs in Nua2Array 


In addition, the following const and type global declarations must be specified in 
your main program: 





const 
RouSize = 252; 
ColSize = 2; 


type 
firray2Type = arrayC1..RouSize, 1..ColSize] of real; 

‘The constant RouSize identifies the maximum number of data pairs you allow 

NunZArray to contain. The number 250 is just an example; you can make RowSize 

any positive integer greater than 1. (The active number of data pairs is controlled 

by NusDataPairs, which must be less than or equal to RouSize.) The constant 

ColSize is fixed at 2 
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Output 
Intercept real The Y intercept of the best straight line. Intercept is 
the value of Y when X equals 0. 
Slope real The slope of the best straight line. Slope is the rate 


of change of Y with respect to X. 

CorrCoeff real The correlation coefficient. This is a number between 
© and 1. The higher its value, the better the fit. A 
perfect fit (with the data all on a straight line) has 
CorrCoeff = 1. The poorer the fit, the closer 
CorrCoeff is to 0, 


Limitations and Error Conditions 


‘You must pass at least two data pairs to LinReg. Otherwise, it cannot calculate any 
‘meaningful straight line. If NunDataPairs is less than 2, the procedure returns a 
value of zero for both Intercept and Slope. In addition, the (otherwise impossible ) 
value of -5.0 is returned for CorrCoeff as an arbitrary code to indicate this error, 


‘Another meaningless case occurs when all of your data pairs have identical X values, 
If this happens, LinReg again returns zero for both Intercept and Slope. Here, 
however, the (otherwise impossible) value of -10.0 is returned for CorrCooff 


If all the Y values are identical (and all the X values are not equal), Slope is set 
to zero, and Intercept is set to the value of Y. In addition, CorrCoeff is set to 1,0 
to indicate a perfect fit 


Sample Usage 


program SamplaUsage0fLinReg; 





type 
frray2Type = arrayC1. RowSize, 1. ColSi; 





var 
NunArray ArrayZType; 
NunDataPairs integer; 
Intercept, Slope, CorrCoeff = real; 


(SI LinReg. PSL) 
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‘BEGIN: 

‘NunQArrayCt, 1] <* 14.9, 
NunZArrayl2, 11 == 17.8; 
NunZArrayl3, 1] == 18.8; 
NunZArrayl4, 1] = 5.6, 
Nun2ArrayC5, 13 <= -3.9, 
Num2Arraylé, 1 '= 25.9, 
NunDataPairs = 6; 

LinReg(NunZArray, Sores Intercept, Slope, CorrCoetf), 
writelnt’ Intercept = *, I 
uritelnt’ Slope 
triteln Correlation Coofficlant = *, CorrCoett 8:6) 








Running this test program produces the following output: 





Intercept = 32. 943148 
Slope = 2.155805 
Correlation Coefficient = 8. 965471 


Subprogram Listing of LinReg.PSL 





Loop index ranging from 1 to NuaDataPairs 
‘The sum of all the X values in your data. SuaX is the sum 
of NunZArrayCJ, 1] for J ranging from 1 to NuaDataPairs, 
‘The sum of all the ¥ values in your data. Sua¥ is the sum 
‘of Nun2ArrayCJ, 2 for J ranging from 1 to NusDataPairs, 
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‘SumXy ‘The sum of (X * Y) for all data pairs 

‘SumxSq ‘The sum of (X * X) for all data pairs 

Suny'Sg ‘The sum of (¥ * Y) for all data pairs 

Val ‘The current value of X 

‘YWal ‘The current value of Y 

Denom ‘The value of a denominator in the expression currently 

being calculated 
Discussion 


Linear regression provides a computational procedure to approximate a set of 
XCY data by a straight line, The method of least squares is used. It calculates the 
line that minimizes the sum of the squares of the calculated Y values subtracted 
from the actual Y values, Once the straight line is defined, you can get a calculated 
value of Y for a given X. If you subtract this calculated Y from the actual Y at that 
X, square the difference, and add the squares together, you get a measure of the 
error in the straight line. The least-squares method provides the straight line that 
minimizes this error. 


Ling defines the straight line by providing its Y intercept and its slope. Intercept 
is the value of Y when X equals 0. Slope is the relative change of Y with respect 
to X. The straight line is thus given by the following formula: 


Y = Intercept + (Slope * x) 


‘The correlation coefficient provides information about how good the fit to the 
straight line actually is. Often this information is valuable by itself. You might do 
an experiment in which you expect a linear dependent relationship to exist. For 
example, assume that the height of (adult) sons can be linearly expressed as a 
function of the height of their fathers. After sampling sufficient data, you can run 
LinReg and find out whether the relationship exists by checking CorrCoeff. 

For each data pair, consider (calculated Y - actual Y) divided by (actual Y - mean 
YY). Suppose that you square these ratios, sum them for all the data pairs, and then 
subtract the answer from 1. CorrCoeff is the square root of this result. CorrCoeff 
hhas the value 1 when the linear relationship is exact. Smaller values indicate less 
linear correlation. A value of 0 means no correlation—Y values are unpredictable 
from a knowledge of the X values. 


Modifications 


None 
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GetChiSq 
Name: GetChisq 
Type: Procedure 
Purpose: To calculate the chi-square statistic 


Calling Sequence: GetChiS9(ProbPerTrial, NunObserved, NuaCels, 
ChiSg) 











Description 


For GetChiSy, it is assumed that an experiment is conducted (or statistical data is 
available) consisting of a finite number of individual trials. Each trial results in one 
of ‘several predetermined outcomes or “cells” Furthermore, the probability of 
achieving each outcome on an individual trial is known (or hypothesized), When 
used with ChiPrab, GetChiS9 provides a statistical test of hypotheses your expe- 
riment may be trying to resolve. 


Input 


ProbPerTrial real Array of the probabilities of achieving each particular 
cell in one trial. Each array element is a number 
between zero and 1. The sum of the elements over 
all the cells must equal 1 


NunObserved real Array of the actual totals achieved for each cell 


NunCel Is integer Number of cells. The first NumCells elements of 
ProbPerTrial and NusObserved contain the relevant 
data. 


In addition, you must provide the following global const and type declarations in 
Your main program. The number 250 is an example; your array size may differ. 








const 
PrraySize = 250, 
type 
ArrayType = arrayCi. ArraySize] of real, 
Output 
ChiSy real Value of chi-square. If ChiSg is negative, an error has 





occurred. (See Limitations and Error Conditions.) 
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Limitations and Error Conditions 


GetChiSg sets ChiS9 to special negative values if GetChiSg detects an error in your 
input data. (Correct values of chi-square are always nonnegative. ) Table 13.1 shows 
the four possible error conditions and the corresponding values of chi-square, 





Table 13.1 
Input Errors Detected by GetChiS 


ChiSg Error 
“10 NunCells is less than 2 
20 ‘An element of ProbPerTrial is nonpositive. 


30 ‘An element of NusObser ved is negative. 
40 ‘The sum of the first NumCel ls elements of ProbPerTr ial does 
‘not equal 1 





A certain tolerance is allowed in the summation of the elements of ProbPerTr ial 
before ChiSg is set to 4.0. (See the Modification section.) 


Be sure that NumCells is not larger than the constant ArraySize set in the const 
block of your main program. 

Sample Usage 

Program SampleUsageOfGetChiSg, 





type 
ArrayType = arrayCt...ArraySize] of real, 


var 
ProbPerTrial, NuaObserved = ArrayType; 
NumGalls, J integer; 
Val, ChiSg real; 


(SI GetChiSy. PSL? 


400 ‘TURBO PASCAL PROGRAM LIBRARY 








lal, NusObserved, NumCells, ChiSg), 
uriteln(’ Chi-square =”, ChiSg) 


Running this test program produces the following output: 


Chi-square = 2. 9285714285E+00 


Subprogram Listing of GetChiSg.PSL 
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Variables 
NuoTrials The total number of trials performed in the experiment, 
NuaTrials is the sum of the first NusGel 1s elements of 
NunQbserved, 
ErrorValue ‘A negative value for chi-square, indicating an error in the 
input data 
Sun ‘The sum of the elements in an array 
J Looping variable 
Description 


‘The chi-square test is a valuable statistical tool for evaluating whether the results 
of an experiment validate a particular hypothesis. When you use GetChiSg with 
GhiPrab, a numerical probability can be assigned to the chance of achieving your 
particular experimental result. If this probability is extremely high or extremely 
low, you have cause to doubt your experimental assumptions, 

‘Chi-square can be used in a wide variety of practical applications. A gambler might 
consider cells to be the various types of poker hands and then test whether a 
particular dealer seems to cheating. A programmer might write a random-number 
generator and test whether it produces good random numbers. Or an emergency 
‘room staff might test whether admissions are statistically biased toward particular 
days of the week. 

‘As chi-square is used here, certain assumptions are made about your experiment, 
‘The probability of achicving each outcome (or “cell” in our terminology) must be 
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known beforehand. Often, however, this hypothesis is the one being tested, and 
the chi-square test can be repeated for different probability distributions. Each 
individual trial must be independent. The test is not valid if the result of one trial 
might influence the result of another trial. In addition, the total number of trials 
(NunTr tals) must be large enough to produce a statistically significant result. ‘The 
ule of thumb is that, for each cell, the value of NuaTr ial times the ProbPerTr ial 
for that cell should be at least 5. If the value is less, the results achieved with the 
ChiProb subprogram lose some validity. 

‘The calculation of chi-square is straightforward. For each cell, the difference be. 
tween the expected number (NuaTrials times ProbPerTr ial for that cell) and the 
actual number (Nusbserved for that cell) is calculated. This difference is squared 
and then divided by the expected number, thus giving the chi-square contribution 
for each cell. The final value is the sum across all the cells of these individual 
contributions. 


Modification 


‘The sum of ProbPerTr1al across all cells must equal 1. You need to allow a certain 
tolerance away from exactly 1 because you (and the computer) cannot represent 
all decimal fractions exactly. (One-fourth is exactly 0.25, but one-third has no such 
finite decimal representation. You may be nonchalant and enter a ProbPerTr ial 
value of one-third as 0.33.) In any case, we allow the sum of ProbPerTr ial to lie 
between 0.999 and 1,001. You may change this tolerance if you want. 


ChiProb - 
Name: OhiProb 
‘Type: real function 


Purpose: To calculate the probability of achieving particular values 
of chi-square 
Calling Sequence: ChiProb(ChiSg, DegFreedom) 














Description 
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Input 
ChiSg real The value of chi-square. ChiSg must be nonnegative. 
DegFreedom integer The number of degrees of freedom. DegFreedom must 
be at least 1 
Output 
ChiProb Given DegFreedoa, the function ChiProb returns the 





probability that an empirical chi-square statistic has a 
value larger than ChiSg. ChiProb is expressed as a 
number between 0 and 1, 


Limitations and Error Conditions 


‘The computational algorithm depends on series summations that can cause real- 
number overflow if the number of degrees of freedom becomes large. Thus, the 
constant MaxDegFreedon defines the largest acceptable value of DegFreedon, Sec the 
Modifications section for more details. The program DoChiSq presented in Chapter 
18 provides a complete chi-square capability that overcomes this limitation. 


‘A fatal run-time error (overflow) may occur if the value of ChiSy is exceedingly 
large (larger than possible in any realistic, practical case). In this instance, the 
desired value of ChiProb is extremely small (probably less than 0.00001) 

ChiProb returns special negative values if it detects an error in your input data. 


(Correct values of ChiProb are always nonnegative.) Table 13.2 shows the three 
detectable error conditions and the corresponding values of ChiProb. 





Table 13.2 
Input Errors Detected by ChiProb 


ChiProb Error 
“10 DegFreedom is less than 1 

20 DegFreedom is greater than MaxDegFreedon 
3.0 ChiSg is negative. 
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Sample Usage 
Program SampleUsageOfChiProb; 
var 
ChiSg 
‘DegFreedom 


($1 ChiProb. PSL? 





‘BEGIN 


writeln(’ Degrees of freedom =“, DegFreedom); 
uriteln(’ Chi-square =’, ChiSg:5:2); 
writeln; 
writeln(*Probability of a larger chi-square =", 
ChiProb(ChiSg, DegFreedom) :7:4) 
END. 


Running this test program produces the following output: 





Degrees of frocdom = 5 
Chi-square = 8.36 





Probability of a larger chi-squari 


Subprogram Listing of ChiProb.PSL 
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Variables 
Term Current value of terms used in series summations 
Denon Denominator in the final division for ChiProb 
z Approximate value of an infinite series involving OhiSy and 
DogFreedon 
2Partial Intermediate value in the calculation of Z 
Value ‘The natural log of Nuserator 
Numerator Numerator in the final division for ChiProb 
Discussion 


‘The following discussion expands the ideas presented with the GetChiS9 subpro- 
‘gram, Some of the terminology used here is developed and explained in the Dis- 
cussion section of GetChiSq. 


‘The number of degrees of freedom (DegFreedom) is one less than the number of 
distinct outcomes (cells) possible in one trial of the experiment. Thus, if ChiProb 
and GetChiSg are used together, DegFreedom is always one less than the variable 
NunGel ls used in GetChiSg, 


‘A remarkable thing about ChiProb is that the function does not depend on the total 
‘umber of trials in the experiment nor on the probabilities of achieving each pos- 
sible outcome, Once chi-square is known, only the value of DegFreedom determines 
the probability that ChiProb calculates. 

‘The chi-square distribution is a continuous, finite-valued (positive) curve defined 
for positive values of chi-square. The chi-square distribution is actually a family 
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of curves (one for each value of DegFreedon) in much the same way that the normal 
distribution is a family of curves (one for cach value of the mean and the standard 
deviation). As chi-square goes toward infinity, the distribution curve approaches 
zero asymptotically. The total area under the curve (that is, the integral) equals 1 
‘The probability calculated by ChiProb is the integral of the distribution curve for 
chi-square, ranging from ChiSg to infinity. As chi-square increases, the value of 
ChiProb decreases, 

If your value of ChiProb is extremely low (maybe less than 0.05 or even less than 
0.01), you have cause to doubt your experimental hypothesis. In the poker example 
mentioned previously, a ChiProb of 0.01 means that the gambler has only a one 
percent chance of being dealt poker hands according to their true probabilities 
(He should look for a different game.) A very high value of ChiProb (say, greater 
than 0,95) is also suspicious. A value this high means that, cell by cell, the ex- 
perimental results match the expected probabilities almost exactly. Such a case 
typically indicates insufficient randomness. Whenever a suspicious value of ChiProb 
‘occurs, repeating the experiment is recommended, if possible. 


Modifications 


1. You may raise the value of MaxDegFreedom to calculate ChiProb for larger 
degrees of freedom. However, fatal run-time errors may occur even if 
ChiSg contains “reasonable” values. (See Limitations and Error 
Conditions.) The computational method still gives correct values if no 
error occurs. 


2. The calculation of Z involves an infinite (converging) sum. We stop the 
series when terms become less than 1.0E-8. (The leading term of the 
series is 1. Thus, this convergence criterion guarantees at least 7 correct 
decimal digits.) You may adjust the convergence criterion if you like. A 
smaller value improves accuracy (slightly); a larger value saves (a small 
amount of) computation time. 
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Business and Finance 





‘The microcomputer has found an ever-growing niche in productivity applications, 
This chapter presents 15 subprograms that perform fundamental business and fi- 
nancial calculations. Most of the subprograms apply to home financial management 
as well as to conventional business. 


Forecasting is a continual concer of most businesses. FutGrow uses a technique 
to make projections based on a growth rate. If you have past-performance data, 
Groufate can determine the correct growth rate to use. FutGrow has many appli- 
cations, including sales, employment, and production, 


‘Most of this chapter deals with money management calculations. The subprograms 
cover four types of time-dependent monetary transactions: (1) investments 
(InvestFY, InvastP, Invest IR, and InvestNt); (2) loans (LoanPay, LoanPrin, and 
LoanTNP); (3) annuities (AnnuFY, AnnuDep, and AnnuTND); and (4) investments with 
withdrawals (WDrawP, UDrawD, and UDrawTM). Each transaction type is character- 
ized by a principal, an interest rate, a term, a compounding frequency, and a final 
value, Some transaction types have a periodic payment or withdrawal. Each sub- 
Program calculates an unknown quantity, given the known quantities. 


Unfortunately, many banking institutions don't follow conventional computational 
formulas exactly. For instance, the regular payment on a loan is often rounded up, 
sometimes to a full dollar, and sometimes even more. For the subprograms in this 
chapter, no results are rounded. Computations in dollars result in full-precision 
real numbers, Figures are rounded to the nearest cent if you display them with 
‘two decimal digits, using Turbo’s real-number formatting For example, the fol- 
lowing statement displays the principal to the nearest cent: 


write(Principal 18:2) 


‘You may find discrepancies between values computed with these subprograms and 
values quoted by banks, Many banks are quite “imaginative” in their interpretations 
of the correct computational formulas. 
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A word of warning to those using the BCD version of Turbo is necessary. Several 
of the subprograms in this chapter do not work with that compiler. See the Lim- 
itations and Error Conditions section of each subprogram you are considering using, 





Name: FutGrow 
‘Type: real function 
Purpose: To project future values based on a growth rate 
Calling Sequence: FutGrou(Rate, Base, NeuTine) 








Description 
This function projects a future value at a specified time, based on an initial value 
and an average growth rate. The business applications are numerous, including sales, 
salaries, employee count, and computer use, (Many applications are possible outside 
of business also.) If you have actual past-performance data, GrouRate can compute 
the growth rate and initial value needed for FutGrow. 


Input 

Rate real ‘The average growth rate, expressed as a percentage, 
for a specific period of time (yearly, monthly, daily, 
ctc.). If Rate is negative, growth is declining. If Rate 
is positive, growth is increasing 

Base real ‘The initial value of the item to be projected. Base 
should be positive for any meaningful case. 

NeuTime integer The time for which the projection is to be made, in 
units of the basic time period. That is, if Rate 
represents daily growth, than cach unit of NewTime 
represents one day. 

Output 
FutGrow real ‘The function FutGrow calculates a future value at 


NesTine, given an initial value (Base) and a growth 
rate (Rate) 
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Limitations and Error Conditions 
If NewTime is less than 2, FutGrow returns the value Base as NeuTime’s projection. 


Sample Usage 

Program Samp|leUsageOfFutGrow, 

var 
Rate, Base, Prediction © real; 
NewTime integer; 


($I FutGrow. PSL) 


‘BEGIN 

Rate ‘= 7,723, 

Base «= 48.281; 

NowTime == 12; 

Prediction :* FutGrow(Rate, Base, NewTime); 

writeln(’ Expected Customers in 12th Month *”, Prediction:6:1); 
write! 
writeln(’ Dollar Value after 8 years at 18.9% =", 

FutGrow(10.8, 1.8, 8):6°3) 





Running this test program produces the following output. The first line represents 
4 projection based on the Sample Usage program from GrouRate. 





Expected Customers in 12th Month = 109.4 


Dollar Value after 8 years at 10.9% = 2 050 
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Subprogram Listing of FutGrow.PSL 





Variables 
Tern ‘The periodic growth factor 
Product Term to the NeuTime power 
J Loop index: 

Discussion 


‘You need to understand clearly the concept of time as used in FutGrou, NeuTime 
expresses the future time in integral values of some time unit. This time unit can 
be days, years, microseconds—whatever you have. However, Rate must express the 
percentage growth rate per one unit of that interval. Thus, if NeuTine is expressed 
in weeks, be sure that Rate is the percentage growth rate per week (not per year, 
per month, or per anything else). 

If you use GrouRate to get Rate and Base, time is automatically in the same unit 
Fepresented by successive values in PastDatafrray. NeuTine, therefore, should be 
in these units also, For example, if GrouRate used monthly sales figures for the last 
6 months (Count was 6), then units of NeuTime should be months also, To get 
projection of monthly sales one month after the PastDataArray data ended, set 
NewT ime to 7. To project the monthly sales one year after the PastDatafrray ended, 
set NewTime to 18, 


Modifications 


None 
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GrowRate 
Name: GrowRate 
Type: Procedure 
Purpose: To calculate the average growth rate of time-series data 
Calling Sequence: GrowRate(PastDataArray, Count, Rate, Base, 0K) 











Description 


GrouRate calculates the average percentage growth rate (and adjusted initial value) 
of time-series data. This kind of data is used regularly in most business environments. 
Examples are sales revenues, positive profits, customer service calls, and manufc- 
turing production. (Many applications outside the business arena are possible also. ) 
‘The past:performance data must be available at equally spaced intervals (years, 
months, days, etc.). GrowRate then provides the average percentage growth rate 
er this interval. Once the growth rate is determined, you can use FutGrou to predict 
future performance. 


Input 
PastDataArray real Array containing the past data. The first clement 
contains the oldest data. Successive array elements 
represent data at equally spaced intervals. All data 
must be positive. 
Count integer Number of elements of PastDataArray to use. 
Count must be at least 2. 


In addition, you must specify the following global type declaration in your main 
program, preferably using the global const declaration shown. The number 250 is 
an example; the size of your array may differ. 





const 
frraySize = 250, 


type 
ArrayType = array(1. ArraySize] of real, 
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Output 
Rate real The average percentage growth rate per interval, 
Rate may be positive, zcro, or negative. 
Base real The adjusted initial value of your data 
K boolean Data validation flag If OK is true, your input data is 


fine. If OK is false, an error is in your data—cither 
Count is less than 2, or an clement of PastDataArray 
is not positive. 


Limitations and Error Conditions 


If an error is detected in your data (Count < 2, or an element in PastDataArray 
is nonpositive), OK is set to false, and the procedure returns to the calling program. 
In this case, the values of Rate and Base are meaningless. If Count is less than 
ArraySize, only the first Count elements in PastDataArray are used, 


‘This procedure will not work with the BCD version of Turbo because that compiler 
does not support the In function on which GrowRate depends, 


Sample Usage 
program Samp |eUsageOfGrouRate; 


const 
ArraySize = 250, 


type 
ArrayType = arrayCt.. ArraySize) of 





var 
PastDatarray © ArrayType; 


Rate, Base real; 
Count, J integer; 
1K boolean; 


($1 GrouRate, PSL) 
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BEGIN 
Count == 5, 
PastDataArrayi3 == 49, 
PastDataArray(2] == 54; 





‘ray(5] °= 68; 
GrouRata(PastDataArray, Count, Rate, Base, OK); 
if OK then 

begin 
urite(’ Customer Grouth Rate for Last’); 
writeln(Count:2, * Months’); 
uriteln; 
_ uriteln(’Grouth Rate % =, Rate’7'3); 
writeln(’ Base Value *”, Base:73) 


else 
writeln(’ Bad input data‘) 
END. 


Running this test program produces the following output: 


Customer Growth Rate for Last 5 Months 





Growth Rate %= 7.723 
Base Value = 48. 281 


Subprogram Listing of GrowRate.PSL 
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Variables 
SunOfLogs ‘The sum of the natural logs of the first Count elements in 
PastDatafrray 
WetghtedSum The sum of the logs weighted toward the most recent data 
Value A value from PastDatafrray 
Logalue ‘The natural log of Value 
Temp ‘Temporary quantity 
J Loop index 
Discussion 


Coupled with FutGrow, Groufate provides a powerful tool for describing past per- 
formance and forecasting future results. GrowFate is best used when your data tends 
to show some semblance of an overall growth trend (whether up or down) instead 


If Rate is negative, your data shows an overall decreasing growth rate. Positive 
values represent increasing growth. 
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GrowRate fits a weighted exponential curve to your data. The procedure requires 

that you have data at regular intervals. If your data is irregularly spaced (or you 

have some missing data), try the PolyFit and TryCurvs programs in Chapter 18. 
Modifications 


None 


InvestFV 


Name: Invest'V 
‘Type: real function 
Purpose: To calculate the final value of an investment 


Calling Sequence: InvestFU(Principal, InterestRate, CompoundYear, 
Numbertonths) 











Description 
InvestFY computes the final value of an investment. You must provide the prin- 
cipal (initial investment), interest rate, compounding frequency, and term of the 
investment. 

Input 
Principal real ‘The initial amount invested 
InterestRate real The annual interest rate expressed as a percentage 
ConpoundYear inte; 





‘The compounding frequency expressed as the 
number of compounding periods per year 


NumberHonths inte, 





‘The term (length) of the investment, in months, For 
example, NunberHonths is 36 for a 3-year investment. 


Output 


InvestFU real The function InvestFV returns the final value of the 
investment. 
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Limitations and Error Conditions 


‘This function does no range checking on your input parameters. If they have non: 
sensical values, a fatal error is possible. Principal should be positive. A negative 
Value results in a negative answer; a value of zero results in an answer of zero, 
InterestRate should be positive (or zero); a large negative value can cause a fatal 
error, ConpoundYear should be positive, or a fatal error is possible. Finally, 
Nunberttonths should be positive, but a negative value docs not cause @ fatal error. 


InvestFV will not work with the BCD version of Turbo because that compiler does 
ot support the In function on which InvestFY depends. 


Sample Usage 
Suppose that you have $15,000 to invest. Two different banks offer 3-year invest- 
‘ments at 14.5 percent annual interest rate. One bank compounds yearly (simple 
interest), but the other bank advertises monthly compounding, The following Sam- 
ple Usage program compares the results of the investment in each case. 


program SampleUsageOf InvestFV, 


var 
Principal, FinalUalue, InterestRate © real, 
CompoundYaar, NumberMonths integer; 


($1 InvestFU, PSL) 


BEGIN 
Principal = 15060, 
InterestRate == 14.5, 
CompoundYear == 12, 
NunberHonths <= 36; 
FinalValue <= InvestFU(Prineipal, InterestRate, 
Compound¥ear, NuaberHonths); 
writeln(’ Final value (compound monthly) = $°, FinalUalue:8:2), 
FinalValue == InvestFU(Principal, InterestRate, 
1, NuaberHonths); 
uriteln(’Final value (compound yearly) = $°, FinalUalue:8:2) 
END. 
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Running this test program produces the following output: 


Final value (compound monthly) = $3114. 11 
Final value (compound yearly) = $22516. 85 


Subprogram Listing of InvestFV.PSL 





Variables 
Growth Multiplicative factor expressing the growth ratio of the 
investment between its initial value and its final value 
Discussion 


Be sure that you express the length of the investment correctly with the input 
parameter NunberHonths, It is the number of months of your investment, Don't 
mistakenly set this parameter to the number of years, The results will be quite 
different! 


CompoundYear specifies the compounding rate as the number of compounding 
periods per year. Thus, yearly, quarterly, monthly, and daily compounding are 
expressed with 1, 4, 12, and 365, respectively. Some banks consider daily com- 
pounding to be 360 times a year. Occasionally someone offers continuous or infinite 
‘compounding, To simulate this kind of compounding, set CompoundYear to a large 
value, say, 10000. The answer will be accurate to (at least) 6 significant digits. 
‘You can use InvestFU to calculate the annual yield of an investment, given the 
interest rate and compounding frequency. For the calculation, set InterestRate 
‘and CompoundYear as you normally would. Then, if you have declared a real variable 
named AnnualYield, the following statement calculates the annual yield as a 
percentage: 
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AnnualYield == InvestFU(198.8, InterestRate, CompoundYear, 
12) - 100.6, 


Interestingly, the annual yield does not get infinitely large as ConpoundYear increases, 
Instead, the annual yield asymptotes (converges) to a finite value. 





Modifications 


None 


InvestP 





Name: InvestP 
‘Type: real function 
Purpose: To calculate the principal of an investment 


Calling Sequence: InvestP(FinalUalue, InterestRate, CompoundYear, 
NuaberHonths) 











Description 


Invest? calculates the principal (initial investment) necessary to reach a certain 
final value, given the investment specifications. You must provide the final value, 
interest rate, compounding frequency, and term of the investment. 


Input 
FinalValue real The final value of the investment 
InterestRate real The annual interest rate expressed as a percentage 


CompoundYear integer The compounding frequency expressed as the 
number of compounding periods per year 

NunberHonths integer The term (length) of the investment, in months. For 
example, NuaberHonths is 36 for a 3-year investment. 


Output 


InvestP real The function Invest? returns the initial amount 
invested (principal). 
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Limitations and Error Conditions 


‘This function does no range checking of your input parameters. If they have 
nonsensical values, a fatal error is possible. FinalValue should be positive. A nega- 
tive value results in a negative answer; 2 value of zero results in an answer 
of zero, InterestRate should be positive (or zero); a large negative value can cause 
a fatal error. CompounéYear should be positive, or a fatal error is likely. Finally, 
Nunberttonths should be positive, but a negative value does not cause a fatal error. 


InvestP will not work with the BCD version of Turbo because that compiler does 
not support the In function on which Invest? depends. 


Sample Usage 
Suppose that you want to invest a lump sum in a college fund for your child. You 
need the investment to mature in 10 years at a value of $20,000. Two different 
banks offer 10-year time deposits at 11.2 percent annual interest rate, One bank 
compounds yearly (simple interest), but the other bank advertises daily com- 
pounding, The following Sample Usage program shows the initial investment needed 
to reach your goal in each case 


Program Samp] aUlsageOf InvestP, 
var 
Principal, FinalValue, InterestRate © real; 
CompoundYear, NunberHonths integer, 


{SI InvestP. PSL) 


BEGIN 
FinalValue = 20000. 20; 
InterestRate «= 11.2, 
CompoundYear == 1, 
NumberMonths «= 120, 
Principal = InvestP(FinalValue, InterestRate, 


CompoundYear, Nuaberttonths); 
writeln(’ Principal (compound yearly) = $°, Principal 7:2); 
Principal == InvestP(FinalValue, InterestRate, 
‘365, NuaberHonths); 
uriteln(’ Principal (compound daily) = $°, Principal:7:2) 
eo 
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Running this test program produces the following output: 


Principal (compound yearly) = $6918.92 
Principal (compound daily) = $6526.72 


Subprogram Listing of InvestP.PSL 





Variables 
Growth Multiplicative factor expressing the growth ratio of the 
investment between its initial value and its final value 
Discussion 


In the Discussion section of InvestFY, the comments regarding the correct spec- 
ification of NunberMonths and CompoundYear are relevant here. See InvestFY, 


Modifications 


None 


InvestIR 





Name: /nvestiR 
‘Type: real function 
Purpose: To calculate the interest rate of an investment 


Calling Sequence: Invest IR(Principal, FinalValue, CompoundYear, 
NumberMonths) 
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Description 


Invest IR calculates the annual interest rate required for an investment to produce 


@ specified return. You must provide the principal, final value, compounding fre- 
‘quency, and term of the investment. 


Input 
Principal real The initial amount invested 
Finalvalue real The final value of the investment 


CompoundYear integer The compounding frequency expressed as the 
number of compounding periods per year 

NunberHonths integer The term (length) of the investment, in months, For 
‘example, NunberHonths is 36 for a 3-year investment. 


Output 


InvestIR real The function Invest IR returns the nominal (annual) 
interest rate expressed as a percentage. 


Limitations and Error Conditions 


‘This function does no range checking of your input parameters. If they have non- 
sensical values, a fatal error is possible. Principal and FinalValue must be positive 
A fatal error results if either of these parameters is negative or zero, CompoundYear 
and Nunberttonths should be positive, but a negative value for either one docs not 
cause a fatal error 





Invest IR will not work with the BCD version of Turbo because that compiler does 
not support the In function on which Invest IR depends 


Sample Usage 
‘Suppose that you have $10,000 to invest, and you want to triple the amount, You 
need the investment to mature in 7 of 8 years. The following Sample Usage program 
shows the nominal (annual) interest required to achieve your goal for each of the 
‘two maturity terms if your bank compounds interest monthly. 
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program SampleUsageOf InvestIR; 


Gries FinalUalue, InterestRate © real; 
CompoundYaar, NumberHonths "integer; 


(SI InvestIR PSL) 













BEGIN 
Principal 
FinalValue 
Compoundvear = 12; 
Numberttonths == 84, 
InterastRate ‘= InvestIR(Principal, FinalUalue, 
GonpoundYear, NunberHonths); 
uriteln(’ Interest Rate (7-year tera) =“, InterestRate’6'3); 
TnterestRate "= InvestIR(Principal,, Finalvalue, 





7, 96); 
uriteln(’ Interest Rate (8-year term) =’, InterestRate'6:3) 


Interest Rat 
Interest Rate (B-year term) = 13. B12 


Subprogram Listing of InvestIR.PSL 





Variables 


None 
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Discussion 


‘The interest rate computed by Invest IR is the nominal (annual) rate. This is the 
rate before any compounding takes effect. It is consistent with the variable 
InterestRate in the other investment subprograms. 


In the Discussion section of InvestFU, the comments regarding the correct spec- 
ification of NumberMonths and CompoundYear are relevant here, See InvestFU. 





Modifications 
None 
InvestNM 
Name: /nvestNM 
‘Type: integer function 





Purpose: To calculate the term of an investment 


Calling Sequence: InvestN(Principal, FinalValu 
ConpoundYear) 


InterestRate, 








Description 


InvestNt calculates the term (length of time) required for an investment to mature, 
given the investment specifications. The term is expressed in months, with any 
partial month rounded to the next higher integer value. You must provide the 





principal (initial investment), final value, interest rate, and compounding frequency 
of the investment. 

Input 
Principal real The initial amount invested 


FinalValue real The final value of the investment 
InterestRate real The annual interest rate expressed as a percentage 


CompoundYear integer ‘The compounding frequency expressed as the 
number of compounding periods per year 
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Output 


InvestN integer The function Invest returns the term (length) of 
the investment, in months. 


Limitations and Error Conditions 


‘This function does no range checking of your input parameters. If they have non- 
sensical values, a fatal error is possible. Principal and FinalValue should be posi- 
tive. Otherwise, a fatal error results (unless both parameters are negative). 
InterestRate and CompoundYear make sense only if they are both positive. A fatal 
error is likely if either parameter has a large negative value. 








InvestNt will not work with the BCD version of Turbo because that compiler does 
not support the In function on which Investh depends. 


See the Discussion section for a general limitation of this function. 


Sample Usage 
‘Suppose that you have $10,000 to put in a time-deposit investment, and your bank 


offers 10.6 percent interest compounded monthly. This Sample Usage program de- 
termines how long it will take to double your money. 


Program Samp! asage0f InvestNt, 


var 
Principal, FinalUalue, InterestRate © real, 
CompoundYear, Nunbertonths integer; 


(SI Investht PSL) 


BEGIN 

Principal = 10008. 00, 

FinalValue = 20000, 29, 

InterestRate «= 16,6, 

CompoundYear °= 12, 

NumberHonths = InvestNM(Principal, FinalValue, 

InterestRate, CompoundYear); 

NumberHonths-3) 


uriteln(’ Term (months) 
END. 
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Running this test program produces the following output: 


Term (months) = 79 


Subprogram Listing of InvestNM.PSL 





Variables 
Real ‘The term of the investment in months, expressed a8 a real 
number. This number is rounded up to produce the 
output of Investht 
Discussion 


For consistency with the other subprograms in the investment family, the term of 
the investment is an integer value, in months. Ifthe real value of the term contains 
4 fraction of a month, the value is rounded to the next full month. 


‘An inaccuracy in the results of Invest is possible if the compounding frequency 
(ConpoundYear) is not at least 12, that is, if compounding is not at least monthly. 
‘This inaccuracy arises because the subprogram may calculate the end of the term 
in the middle of a compounding period. The results are exact only if the end of 
each month coincides with the end of a compounding period, 
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Modification 
‘You can have the function return a real value instead of an integer value. A real 
value shows a fraction of a month if the term is not an integral number of months. 
‘Change the last integer to real in the line denoted by (Mod. #1a). Then replace 
all four lines indicated by (Had. 1b) with the following single statement: 


Investh := RoalNt 


LoanPay 
Name: LoanPay 
Type: real function 


Purpose: To calculate the regular payment for a loan 


Calling Sequence: LoanPay(Principal, InterestRate, TotalNusPay, 
NuaPayPer'¥r) 








Description 


LoanPay computes the amount of each payment required to pay back a loan, For 
most loans, these payments are made monthly, but LoanPay accommodates other 
payment schedules as well. All payments (except possibly the last) are assumed to 
be equal. You must provide the amount of the loan, the annual interest rate, the 
term of the loan, and the number of payments made per year. 


Input 
Principal real_—-The principal of the loan (amount borrowed) 
InterestRate real The annual interest rate expressed as a percentage 


TotalNumPay integer The term of the loan, expressed as the total number 
‘of payments to be made 


NunPayPerYr — inte, 





‘The number of payments made per year, For most 
Joans, this number is 12 (monthly repayment). The 
term of the loan in years is TotalNumPay / 
NunPayPerr. 
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Output 


LoanPay real ~The function LoanPay returns the amount of each 
payment required to pay back the loan. 


Limitations and Error Conditions 


‘This function does no range checking of your input parameters. If they have non- 
sensical values, a fatal error is possible. Principal should be positive, but a non- 
positive value docs not cause a fatal error. InterestRate, TotalNuwPay, and 
NunPayPer¥r should also be positive. A value of zero or a large negative value for 
any of these parameters can cause a fatal error. 


LoanPay will not work with the BCD version of Turbo because that compiler docs 
not support the In function on which LoanPay depends. 
Sample Usage 


‘Suppose that you want to finance a house for $82,000. Your lending company offers 
20- of 30-year loans at 11.5 percent. The following Sample Usage program shows 
the monthly payment required to pay back either a 20-year loan or a 30-year loan. 


program SampleUsaga0fLoanPay; 


var 
Principal, Payment, InterestRate ° real; 
TotalNunPay, NunPayParYr integer, 
(SI LoanPay. PSL? 
‘BEGIN 


Principal <= 82000. 02, 
InterestRate <= 11.5; 
TotalNuPay <= 240, 
NunPayPerYr <= 12, 
Paynent “= LoanPay(Principal, InterestRate, TotalNunPay, 
NumPayPerYr; 
uriteln(’ Payment (20-year term) = $', Paynent=6:2); 
uriteln(’ Payment (32-year term) = $°, LoanPay(Principal, 
InterestRate, 368, NuaPayPerr):6:2) 
END. 
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Running this test program produces the following output: 


Payment (28-year term) = $874.47 
Paymont (38-year term) = $812 64 


Subprogram Listing of LoanPay.PSL 





Variables 
Temp ‘Temporary quantity 


Discussion 
Most loans are paid back monthly. In such a case, NumPayPerYr is 12, and 
TotalNusPay is 12 times the length of the loan in years. However, LoanPay can 
handle other payment schedules as well. For example, a loan paid back quarterly 
‘over 15 years has NuePayPerYr equal to 4 and TotalNuaPay equal to 60. 


‘This subprogram computes the regular (constant) payment made each payment 
period. Typically, the last payment is not equal to the regular payment because the 
remaining loan balance in the last payment period is often less than the regular 
Payment. Use the Mortgage program in Chapter 18 to calculate the amount of the 
last payment. 


Modifications 


None 
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Name: LoanPrin 
‘Type: real function 
Purpose: To calculate the principal for a loan 


Calling Sequence: LoanPrin(Paynent, InterestRate, TotalNunPay, 
NunPayPerYr) 





Description 


Loan in computes the principal (initial amount borrowed) for a loan. You must 
provide the amount of each payment, the annual interest rate, the term of the loan, 
and the number of payments made per year. For most loans, payment is made 
monthly, but LoanPr in accommodates other payment schedules as well. 


Input 
Payment real The amount of each payment 
InterestRate real The annual interest rate expressed as a percentage 
TotalNuaPay integer The term of the loan, expressed as the total number 


of payments to be made 


NunPayPerYr Integer The number of payments made per year, For most 
Joans, this number is 12 (monthly repayment). The 
term of the loan in years is TotalNuPay / 
NusPayPar'r. 


Output 


LoanPrin real The function LoanPrin returns the principal of the 
loan (the initial amount borrowed). 


Limitations and Error Conditions 


‘This function does no range checking of your input parameters, If they have non- 
sensical values, a fatal error is possible. Payment should be positive, but a nonpositive 
‘value does not cause a fatal error. InterestRate, TotalNunPay, and NunPayPerYr 
should also be positive. A value of zero or a large negative value for any of these 
parameters can cause a fatal error. 
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LoanPr in will not work with the BCD version of Turbo because that compiler does 
ot support the In function on which Loanrin depends. 


Sample Usage 
‘Suppose that you want to finance the purchase of a new car. You can afford a 


monthly payment of up to $300. Your lending company offers car loans for 4 or 


5 years at 16 percent. The following Sample Usage program shows how much you 
‘can borrow for each of these loan terms. 


program SamplaUsage0fLoanPrin; 
var 


Principal, Payment, InterestRate : real; 
TotalNunPay, NusPayParYr Ante 





($1 LoanPrin. PSL) 


BEGIN 
Payment 300.00, 
InterestRate == 16 
TotalNumPay + 48, 
NunPayParYr = 12, 
Principal == LoanPrin(Payment, InterestRate, TotalNuePay, 
NusPayPar Yr; 
uriteln(’ Principal (4-year term) « $°, Principal:8:2), 
uriteln(’ Principal (S-year term) = $°, LoanPrin(Payment, 
InterestRate, 6, 12):8:2) 








Running this test program produces the following output: 





Principal (4-year term) = $1@585. 64 
Principal (S-year term) = $1236. St 
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Subprogram Listing of LoanPrin.PSL 





Variables 
Temp ‘Temporary quantity 


Discussion 


In the Discussion section of LoanPay, the comments regarding the specification of 
the loan payment schedules are relevant here. Sce LoanPay 


Modifications 
None 


LoanTNP 
Name: LoanTNP 


Type: integer function 


Purpose: To calculate the total number of prayments required to pay 
back a loan 





Calling Sequence: LoanTN(Principal, Payment, InterestRate, 
NuoPayPer'r) 
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Description 
LoanTHP calculates the term (length of time) required to pay back a loan. This term 
is expressed as the total number of payments required. You must provide the prin- 
cipal (amount borrowed), amount of each payment, annual interest rate, and num- 
ber of payments made per year. The payback in years can be found by dividing the 
total number of payments by the number of payments made per year. 


Input 
Principal real ‘The amount borrowed 
Payment real The amount of each payment 


InterestRate real The annual interest rate expressed as a percentage 


NunPayPerYr integer ‘The number of payments made per year. For most 
Joans, this number is 12 (monthly repayment). 


Output 


LoanTP integer ‘The function LoanTN? returns the total number of 
payments required to pay back the loan, 


Limitations and Error Conditions 


LoanTNP checks that the quantity (Principal * InterestRate / Payment / 
NusPayPerYr) does not exceed 100. If it does, your loan payments are 100 small 
to achieve amortization, and the number of payments required is infinite. LoanTNP 
returns a value of 0 (zero) as an error warning if this condition occurs. 


No other range checking of your input parameters is done. All input values should 
be positive, A fatal error is possible if a value is negative or zero. 


LoanTN? will not work with the BCD version of Turbo because that compiler does 
‘not support the In function on which LoanTNP depends. 


Sample Usage 


Imagine that a friend is willing to loan you $15,000 at 15.5 percent interest on the 
condition that you pay him back in monthly payments of $325. The following Sample 
Usage program shows how many payments you must make to repay this loan. 
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program SaapleUsageOfLoan™N®, 


P rrinsiel Payment, InterestRate = real; 
TotalNumPay, NumPayPer'r > Integer; 


(ST LoanTNP. PSL) 


BEGIN 
Principal == 1500.09, 
Payment == 325.08, 
InterestRate = 15.5, 


NunPay 12, 
cs es co Ne elem ePaper ft tarastata 
uriteln( Total nunber of payments oh TotalNunPay '3) 


Running this test program produces the following output: 


Total nunber of payments = 71 


Subprogram Listing of LoanTNP.PSL 
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Variables 

Temp ‘Temporary quantity. It must be less than 1, 

Real TP The total number of payments, expressed as a real 
‘number. This number is rounded up to produce the 
output of LoanTH?. 

Discussion 


For consistency with the other subprograms in the loan family, the term of the 
loan is an integer value equal to the total number of payments to be made. If the 
real value of this term contains a fractional part, the value is rounded up to produce 
the integer output required. 


Modification 


You can have the function return a real value for the total number of payments 
instead of returning an integer value. A real value shows whether a fraction of 
a payment is required. Change the last integer to real in the line indicated by 
(Mod, 1a). Then replace all four lines designated by (Hod. #1b) with the following 
single statement 





LoanTNP '= Real TN 


AnnuFV 





Name: AnnuFV 
‘Type: real function 
Purpose: To calculate the final value of an annuity 


Calling Sequence: fnnuFU(Daposit, InterestRate, TotalNumDep, 
NumDepPer Yr) 











Description 
AnnuFU computes the final value of an investment in which equal deposits are made 
at regular intervals. Interest is assumed to compound with each deposit. You must 
provide the amount of each deposit, the nominal (annual) interest rate, the term 
of the annuity, and the number of deposits made yearly. 
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Input 
Deposit real ‘The amount of each deposit 
InterestRate real ‘The annual interest rate expressed as a 


Percentage 


TotalNumDep integer The term of the annuity, expressed as the total 
number of deposits to be made 


‘The number of deposits made cach year. The 
term of the annuity in years is TotalNumDep / 





NumDepParYr ints 


NuaDepPer Yr. 
Output 
AnnuFU real ‘The function AnnuFV returns the final value of 
the annuity. 


Limitations and Error Conditions 


All of your input parameters should be positive. AnnuFY does not do any range 
checking, If an input parameter is negative, a nonsensical answer results, A fatal 
error occurs if InterestRate or NunDepPer'r is zero. AnnuFU returns a value of 0 
(zero) if Deposit is zero or TotalNuaDep is not positive. 


Sample Usage 


Suppose that you deposit $75 into a savings account at the end of every two weeks. 
‘Your bank offers 8.5 percent interest, which is compounded with each deposit. 
‘The following Sample Usage program shows the value of this account after 1 year 
and after 2 years. 


program SampleUsagaDfAnnuFU; 

var 
Deposit, FinalValue, InterestRate « real, 
TotalNumDep, NumDepPer'r © integer; 


($1. AnnuFU. PSL) 
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BEGIN 
Deposit + 75.00, c 
InterestRate == 8.5; 
TotalNunBep == 26, 





NumDepPer 26; 
FinalValue == re InterestRate, 


writeln(’ Final Value a fe +S, Finalels y 

FinalValue == AnnuFU(Deposit, InterestRate, 52, NumDepPerYr); 

writeln(’ Final Value (2 years) = $', FinalValue 
‘END. 






Running this test program produces the following output: 


Final value (1 year) = $2831.81 
Final value (2 years) = $4243.57 


Subprogram Listing of AnnuFV.PSL 





Variables 
Product ‘Temporary multiplicative product 
Zt Loop index 
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Discussion 

Annuities come in many forms. For our purposes, they refer to any fixed-amount 
deposits made at regular intervals into savings. The interest is assumed to compound 
at cach deposit, 

Be sure that you express the term of the annuity correctly. NunDepPerYr is the 
number of deposits made per year. For annual deposits to an annuity, NumDepPer Yr 
is simply 1. For monthly deposits into a “Christmas Club” account, NunDepPer¥r 
is 12, TotalNunDep is the total number of deposits made over the life of the an- 
uity. This number does not need to be an even multiple of NunDepPerYr. (That 
is, the term of the annuity does not have to be an integral number of years.) For 
example, if you start a Christmas Club in April, TotalNunDep is 9, whereas 
NunDepPerYr is 12. 


Modifications 


None 


AnnuD: 








Name: AnnuDep 
Type: real function 
Purpose: To calculate the regular deposit for an annuity 


Calling Sequence: AnnuDep(FinalValue, InterestRate, TotalNunDep, 
NuaDlepPer'r) 








Description 
AnnuDep computes the amount of each deposit required for an annuity to reach a 
specified final value in a given amount of time. All deposits are equal and made at 
regular intervals, Interest is assumed to compound with cach deposit. You must 
provide the final value of the annuity, nominal (annual) interest rate, term of the 
annuity, and number of deposits made yearly 





Input 
FinalValue real The final value of the annuit 





InterestRate real The annual interest rate expressed as a percentage 
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TotalNumDep inte: 





The term of the annuity, expressed as the total 
number of deposits to be made 


NunDepPerYr integer The number of deposits made each year. The term of 
the annuity in years is TotalNusDep / NuaDepPer'r. 


Output 


fnnuDep real The function AnnuDep returns the amount of each 
deposit. 


Limitations and Error Conditions 
All of your input parameters should be positive. AnnuDep does not do any range 
checking, If an input parameter is negative, a nonsensical answer results. A fatal 


error occurs if InterestRate is zero, NuaDepPerr is zero, or TotalNunDep is not 
Positive. AnnuFU returns a value of 0 (zero) if FinalValue is zero. 


Sample Usage 
‘Suppose that you want to start an annuity that matures at $15,000 in 10 years. Your 
bank offers 9 percent interest, You can make deposits yearly or quarterly, The 
following Sample Usage program compares the size of your required regular deposits 
for each depositing alternative. Interest is assumed to compound with each deposit, 


program SampleUsage0ffnnudep, 


var 
Deposit, Finallalue, InterestRate = real; 
TotalNumBep, NunDepPer'r integer; 
($1 AnnuDep. PSL) 
BEGIN 
FinalValue = 15000. 28, 
InterestRate «= 9.8, 





TotalNunDep := 10, 

NumDepPor¥r = 1, 

Deposit fnnuDep(FinalValue, InterestRate, 
TotalNuaDep, NuaDepPerYr); 

writelnt’ Deposit (yearly) = $, Deposit 6:2), 

Deposit = AnnuDep(FinalValue, InterestRate, 40, 4), 

uriteln(’ Deposit (quarterly) = $°, Deposit:6:2) 

END. 
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Running this test program produces the following output: 


Deposit (yearly) = $987.98 
Deposit (quarterly) = $235.16 


Subprogram Listing of AnnuDep.PSL 





Variables 
Product Temporary multiplicative product 
J Loop index 

Discussion 


In the Discussion section of AnnuFY, the comments regarding the correct specifi- 
cations of TotalNuaDep and NuaDepPer'r arc relevant here, See AnnuFY. 


Modifications 
None 
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AnnuTND 


Name: AnnuTND 
Type: integer function 
Purpose: To calculate the total number of deposits for an annuity 


Calling Sequence: AnnuDep(Deposit, FinalValue, InterestRate, 
NuaDepPer'r) 














Description 
AnnuTND computes the term (length of time) required for an annuity to mature, 
‘This term is expressed as the total number of deposits required. You must specify 
the amount of cach deposit, the final (maturity) value, the annual interest rate, and 


the number of deposits made per year. All deposits are equal and made at regular 
intervals. Interest is assumed to compound with cach deposit 


Input 

Deposit real ‘The amount of each deposit 

FinalValue real ‘The final value of the annuity 

InterestRate real ‘The annual interest rate expressed as a 

Percentage 

NunflepPerYr integer The number of deposits made each year 
Output 

fAnnuTND The function AnnuTND returns the total number 





of deposits required for the annuity to mature. 


Limitations and Error Conditions 


Each input parameter should be positive. AnnuTND does not do any range checking, 
If any input parameter is zero or sufficiently negative, a fatal error occurs. 


This function will not work with the BCD version of Turbo because that compiler 
does not support the In function on which AnnuTND depends. 
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Sample Usage 


Suppose that you want fo start an annuity that matures at $7,500. You can make 
monthly payments of $100, and your bank offers 7.75 percent annual interest for 
such an account. The interest compounds with cach deposit. The following Sample 
Usage program shows how many deposits you must make to achieve your goal 


program SamplelsageOfAnnuTND, 


var 
Deposit, FinalVelue, InterestRate © real; 
TotalNumDep, NunDepPer'r integer; 
(ST AnnuTND. PSL) 





IN 
Deposit = 108.08, 
FinalValue <= 7500. 08; 
IntarastRate + 7.75; 
NumDepPer'Yr «= 12; 
TotalNunDep <= AnnuTND(Deposit, FinalValue, InterestRate, 
NuaDepPer'r); 
uriteln(’ Total number of deposits *’, TotalNunDep'3) 
END 


Running this test program produces the following output 


Total number of deposits = 62 


Subprogram Listing of AnnuTND.PSL 
ation AnnuTND(Deposit, FinalValue, InterestRate: real; 
NumDepPer Yr = 


e integer) integer; (Mod. 1a) 
> ee 
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Variables 
Temp ‘Temporary value 
Real TND ‘The total number of payments, expressed as a real 
number. This number is rounded up to produce the 
‘output of AnnuTND. 
Discussion 


For consistency with the other subprograms in the annuity family, the term of the 
annuity is an integer value equal to the total number of deposits to be made. If 
the term’s real value contains a fractional part, the value is rounded up to produce 
the integer output required. 


Modification 


‘You can have the function return a real value for the total number of deposits 
instead of returning an integer value. A real value shows whether a fraction of 
‘a deposit is required. Change the last integer to real in the line indicated by 


(Hod. #12). ‘Then replace all four lines designated by (Hod. 1b) with the following 
single statement: 


AnnuTND <= Real TND 
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WDrawP 
Name: WDrawP 


Type: real function 


Purpose: To calculate the principal for an investment with 
withdrawals 





Calling Sequence: UDrauP(Uithdrawal, InterestRate, TotalNunii, 
NualiPerYr) 








Description 
UDrawP computes the principal (initial investment) required to sustain an invest 
ment with regular withdrawals for a given length of time. The amount of each 
withdrawal is the same. Withdrawals are made at fixed intervals, and interest is 
assumed to compound with each withdrawal. The balance of the investment is zero. 
at maturity. You must specify the amount of cach withdrawal, the nominal (annual ) 
interest rate, the term of the investment, and the number of withdrawals made per 


year. 
Input 
Withdrawal real ‘The amount of each withdrawal 
InterestRate real “The annual interest rate expressed as a 
percentage 
TotalNun integer The term of the investment, expressed as the 
total number of withdrawals to be made 
NunPer Yr integer ‘The number of withdrawals made each year, 
‘The term of the loan in years is TotalNuall / 
NuslPerr 
Output 
UDrawe real ‘The function UDrawP returns the principal 


initial investment) required. 


Limitations and Error Conditions 


Each input parameter should be positive. The function does not do any range check- 
ing. A fatal error can occur if InterestRate or NusLPer Yr is zero or negative, UDrauP 
returns a value of 0 (zero) if Uithdrawal is zcro or TotalNuall is not positive. 
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Sample Usage 
‘Suppose that you want to make monthly withdrawals of $150 from a savings account 
‘over a period of 3 or 4 years, (The balance of the account is zero at maturity.) 
‘Your bank offers 10.5 percent annual interest compounded with each withdrawal. 
‘The following Sample Usage program compares the initial investment required for 
each of these two terms. 

Program SampleUsageOfWDrauP; 


var 
Principal, Withdrawal, InterestRate ~ real; 
TotalNuml, NumPerYr © integer; 


($1 UDrawP. PSL) 


BEGIN 
Withdrawal 





Principal = UDrawP(Uithdrawal, InterestRate, TotalNusll, 
NumiPerr ; 
writaln(’ Principal (3-year term) = $, Principal:7'2), 
writeln(’ Principal (4-year term) = $°, UDrawP(Ui thdrawal, 
InterestRate, 48, NumliPerYr):7:2) 
END. 


Running this test program produces the following output: 


Principal (3-year term) = $4615.04 
Principal (4-year term) = $5858.60 


Subprogram Listing of WOrawP.PSL 
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Variables 
Product ‘Temporary multiplicative product 
J Loop index 

Discussion 


Be sure that you express the term of the investment correctly. NunParYr is the 
number of withdrawals per year. The number is 12 for monthly withdrawals and 
1 for yearly withdrawals. The entire term of the investment is reflected in Tota lNunil, 
which is the total number of withdrawals over the life of the investment. Tota lNuald 
does not have to be an integral multiple of Nunlerr. In other words, the macurity 
term does not have to be an integral number of years (unless NumPerr is 1). For 
example, if withdrawals are quarterly for 3 1/2 years, NuolPerr is 4, and Tota lNuold 
is 14, 


Modifications 
None 


WDrawWD 


Name: WDrawWD 
Type: real function 


Purpose: To calculate the maximum periodic withdrawal from an 
investment 


Calling Sequence: UDrauiiD(Principal, InterestRate, TotalNuml, 
Number) 
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Description 
UDrawD computes the maximum regular withdrawal amount that enables an in- 
‘Vestment to sustain itself for a given length of time. The amount of each withdrawal 
is the same. Withdrawals are made at fixed intervals, and interest is assumed to 
compound with each withdrawal, The balance of the investment is zero at maturity. 
‘You must specify the principal (amount of the initial investment ), nominal (annual) 
interest rate, term of the investment, and number of withdrawals made per year. 








Input 
Principal real ‘The principal (initial investment) 
InterestRate real ‘The annual interest rate expressed as a 
percentage 
TotalNunll ‘The term of the investment, expressed as the 
total number of withdrawals to be made 
Numer Yr inte ‘The number of withdrawals made each year 
‘The term of the loan in years is TotalNunll / 
NualPerr. 
Output 
UDrawdiD real ‘The function UDrawiD returns the amount of 
each withdrawal. 


Limitations and Error Conditions 


Each input parameter should be positive. The function does not do any range check- 
ing, A fatal error can occur if InterestRate, TotalNuell, or NunlPerYr is zero or 
negative. UDraukD returns a value of 0 (zero) if Principal is zero. 


Sample Usage 
Suppose that you have $12,500 to invest in an income-producing time deposit. Your 
bank offers 11 percent annual interest if withdrawals (and compounding ) are once 
@ year, You do not want the account balance to reach 0 (zero) until 10 or 12 
years. The following Sample Usage program compares the maximum withdrawal 
you can make for each of these two terms. 
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program SampleUsageOfUDrawtiD, 


var 
Principal, Withdrawal, InterestRate = real; 
TotalNumll, NumliPer Yr + Integer; 


($1 UDrawlD, PSL) 


‘BEGIN 
Principal 
InterestRate 
TotalNumld 
Numer Yr 4 
Withdrawal «= UDrawiD(Principal, InterestRate, TotalNuall, 

‘NuabPer Yr), 


2); 








urtteln(’Uithdraval (18-year term) = $', Withdrawal 
writeln(’ Withdrawal (12-year term) = $, UDrawiD(Pr: 
InterestRate, 12, NuabPerYr):7:2) 





END. 
Running this test program produces the following output: 


Uithdrawal (18-year term) = $2122 52 
Withdrawal (12-year term) = $1925.34 


Subprogram Listing of WDrawWD.PSL 
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Variables 
Product ‘Temporary multiplicative product 
J Loop index 

Discussion 


In the Discussion section of UDrawP, the comments regarding the specification of 
the length of the investment are relevant here. See UDrauP. 


Modifications 


None 


WDrawINW 
Name: WDrawTNW 


Type: integer function 


Purpose: To calculate the total number of withdrawals until an 
investment és depleted 


Calling Sequence: \DrawTNJ(Principal, Uithdraual, InterestRate, 
‘NualiPer¥r) 








Description 

UDrawTNJ computes the term (length of time) an investment can sustain itself if 
periodic withdrawals are made. This term is expressed as the total number of 
withdrawals before the investment is depleted to zero value. The amount of each 
withdrawal is the same, and the withdrawals occur at regular intervals, Interest is 
compounded with each withdrawal. You must specify the principal (initial in- 
yestment ), amount of each withdrawal, nominal (annual ) interest rate, and number 
‘of withdrawals made per year. 


Input 
Principal real ‘The principal (initial investment) 
Withdrawal real ‘The amount of each withdrawal 
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InterestRate real ‘The annual interest rate expressed as a 
percentage 
NunlPerr integer The number of withdrawals made each year 
Output 
UDrawTh integer The function UDrawTM returns the total number 
‘of withdrawals until the investment depletes 10 
zero value 


Limitations and Error Conditions 


UDrauTMU checks that the quantity (Principal * InterestRate / NunlPerYr / 
Uithdrawal ) does not exceed 100. If it does, your withdrawals are not large enough 
to deplete the investment, and the number of withdrawals required is infinite. 
UDrawTNJ returns a value of O (zero) as an error warning if this condition occurs, 


No other range checking of your input parameters is done. All values should be 
positive. A fatal error is possible if a value is negative or zero, 


‘This function will not work with the BCD version of Turbo because that compiler 
‘does not support the In function on which UDrawTNd depends. 


Sample Usage 


‘Suppose that you have $10,000 to invest in an income-producing time deposit. Your 
bank offers 11.5 percent annual interest if withdrawals (and compounding) are 
either monthly or every other month. You want to withdraw $400 cach time, ‘The 
following Sample Usage program compares the total number of withdrawals possible 
in each case before the balance reaches zero, 





program Samp] eUsageOfUDrauTN, 
var 
Principal, Withdrawal, InterestRate © real 
TotalNumll, NunlPerYr integer; 
(SI UDrawTNs, PSLD 
BEGIN 
Principal <= 10000. 08; 
Withdrawal <= 400.9; 
InterestRate «= 11.5; 
NuolPerYr <= 6 
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TotalNunld «= UDrawTNu(Principal, Withdrawal, InterestRate, 
NuliPorYr); 
ete nloe number of withdrawals (bimonthly) =, 


fotalNuml:3); 
Total = UDrawTMu(Principal, uit 
InterestRate, 12), 
writeln(’ Total number of withdrawals wonthly) ws 
TotalNumdl:3) 
‘END. 


Running this test program produces the following output: 


Total number of withdrawals (bimonthly) = 35 
Total number of withdrawals (monthly) = 29 


Subprogram Listing of WOrawTNW.PSL 





BUSINESS AND FINANCE 453 





Variables 

Temp ‘Temporary quantity. It must be greater than zero, or the 
error condition occurs. 

RealTN ‘The total number of withdrawals, expressed as a real 
number. This number is rounded up to produce the 
output of UDrawTNd. 

Discussion 


For consistency with the other subprograms in the investment withdrawal family, 
the term of the investment is an integer value equal to the total number of with- 
drawals allowed. If the real value of this term contains a fractional part, the value 
is rounded up to produce the integer output required. 


Modification 


You can have the function return a real value for the total number of withdrawals 
instead of returning an integer value. The real value shows whether a fraction of 
1 withdrawal occurs. Change the last integer to real in the line denoted by 
(Hod. #1a). Then replace all four lines designated as (Mod, *1b) with the following, 
single statement: 


UDrawTNJ © Real TN 
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Examining and Altering 
the Computer Environment 





‘This chapter presents three subprograms that examine the computer environment 
and one subprogram that changes the environment. GetSys1D determines which 
type of IBM PC the program is running on, GetEguip determines what equipment 
isattached to the computer, and Ui dlode determines what video mode the program 
is currently using. The fourth subprogram, UideoChg, changes the currently active 
screen if the computer has both the Monochrome Adapter and the Color/Graphics 


Adapter. 


GetSysID 
Name: GetSysID 
‘Type: char function 
Purpose: To determine which type of IBM PC is in use 
Calling Sequence: GetSys1D 











Description 
GetSysID examines a location in the IBM PC’s ROM (read-only memory) to de- 
termine which computer model is being used. Because the different models have 
different characteristics and capabilities, you may want to use this subprogram if 
your main program is being distributed to other people. The technique used in 
GetSys1D distinguishes among the original IBM PC, the IBM PC XT, the IBM PGjr™, 
and the IBM Personal Computer AT. 





Input 


None 


455 
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Output 
GetSysID char The function GetSysID returns a char value with the 
following meanings: 

4 IBM PC 

x IBM PC XT or Portable PC 

J IBM PGr 

A IBM Personal Computer AT 

U Unknown 


Limitations and Error Conditions 


IBM is not perfectly consistent in the way it implements the system identification 
byte in ROM, but the results of this subprogram are generally accurate. Some original 
PCs and XTs may be branded with the same ID, but the PGjr and the Personal 
Computer AT always should be indicated correctly. Fortunately, these discrepancies 
are not a practical problem. The PC and the XT are extremely similar, but the PGjr 
and the AT have many differences. Confusing the PC and the XT (or Portable) is 
seldom a problem, and the other IDs are reliable. Some “compatible” computers, 
however, are inconsistent in the implementation of the system identification feature. 
Some computers use the same indicators IBM uses, but other computers use other 
values. 


Sample Usage 

program SamplelsagoOfGetSysID, 
(SI GetSysiD. PSL) 

BEGIN 


writeln(’ This computer has a system ID of ’, GetSysiD) 
END. 


‘This sample program produces the following output when the program is run on 
an original IBM PC: 


This computer has a system ID of P 
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Subprogram Listing of GetSysID.PSL 





Variables 
SysID ‘The contents of the system identification memory location 


Discussion 
None 


Modifications 
You can update the list of computer models as new computers are announced. 
‘Add a semicolon to the end of the line indicated by (Mod. #12 and insert more 
lines after it. For example, if a new model called the QT becomes available and it 
hhas a system ID of hex FA (decimal 250), you add the following line (the semicolon 
‘on the last line before else should be omitted): 


SFA: GetSysID =’ 
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GetEquip 
Name: GetEquip 
Type: Procedure 
Purpose: To determine the computer's equipment configuration 
Calling Sequence: GetEquip(EquipList, MemSize) 














Description 


‘The GetEquip subprogram uses two ROM BIOS services to retrieve information 
about the equipment configuration of the computer. Of most interest are the num: 
ber of printers installed, the number of RS-232 serial ports installed, the number 
of floppy disk drives, and the amount of memory installed. This information is helpful 
for programs that deal with peripheral devices. For example, if the computer has 
‘no printer interface installed, a program should not attempt to send data to a printer. 
‘This subprogram provides a means of checking. 


Input 


None 


Output 


Epuiplist integer Two bytes of bit settings that indicate the current 
‘equipment configuration. See table 15.1 in the 
Discussion section for details 


MenSize integer The amount of RAM, in kilobytes (K), the computer 
hhas, based on the system board switch settings. In 
‘other words, 256 means 256K of RAM (256 times 
1,024, or 262,144 bytes). 


Limitations and Error Conditions 


The information provided by this subprogram is limited by the accuracy of the ROM 
BIOS services used. In particular, the EguipList bit settings were devised when 
the original IBM PC was designed, and the settings have not been updated to include 
all subsequent peripherals. Even with these limitations, however, the available in- 
formation can be useful in many programming cases. 
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Sample Usage 
program Samp|eUsage0fGetEguip; 
type 
String4 = stringl4], 
var 
EquipList, MemSize integer; 
Temp byte; 


($1 GetEquip. PSL) 
{$1 IntToHex, PSL? 


‘BEGIN 
GetEguip(Eguiplist, MenSize); 
writeln(’ EguipList =", IntToHex(Eguiplist), ‘ (hex)’); 
writeln(MeaSize, “K of RAM installed’); 
Temp :* hi(EguipList) shr 6; 
writeln(Temp, ‘ printer(s) installed’ ); 
Temp ©= hiCEguipList) and SOF shr 1, 
uriteln(Temp, ‘ RS-232 serial port(s)’); 
Af (lo(EguipList) and $81) = 1 then 
begin 
Temp := lo(EguipList) shr 6 + 1, 
writeln(Temp, ‘ floppy disk drive(s)’ ) 
end 
else 
uriteln(’No floppy disk drives’ ) 
END. 


‘This sample program displays the EguipList data in hexadecimal notation (using 
the IntToHex subprogram, which you must make available), and the memory size 
in decimal notation. The program then demonstrates how to select some peripheral 
information from the bits in EguipList, displaying on the scrcen the peripherals 
found. 





EquipList = 4270 Chex) 
512K of RAM installed 

1 printer(s) installed 
4 RS-232 serial port(s) 
2 floppy disk drive(s) 
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Subprogram Listing of GetEquip.PSL 





Variables 
Reg ‘The standard internal registers used in passing data to and 
from Turbo’s asdos procedure 
Discussion 


‘Table 15.1 explains the bit settings in EquipList. A few more details are available 
in IBM's Personal Computer Technical Reference and in The Peter Norton Pro- 
grammer’s Guide to the IBM® PC (Microsoft Press, 1985). 


‘The standard bit-numbering scheme for the IBM PC (Intel 808x microprocessor 

family) is used. In other words, bit 15 is the high-order bit of the high-order 
byte [byte hi (EguipList) in Turbo]. Bit 7 is the high-order bit of the low-order 
byte [1o(EgutpList)]. CGA refers to the IBM Color/Graphics Adapter. The Sample 
Usage program demonstrates how to test bits and retrieve numbers from EquipLi st. 


Modifications 


None 
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Table 15.1 
Bit Settings in EguipList 


Bits Set Interpretation 
15,14 Number of printers attached 








13 On if serial printer attached to PCjr 
12 On if game 1/O attached 
n-9 Number of RS-232 serial ports 
8 Off if DMA chip installed 
26 Number of floppy disk drives minus 1 
54 Initial video mode (01 = 40x25 CGA, 10 = 80x25 CGA, and 11 
= monochrome ) 
3,2 System board RAM (11 = 64K or full) 
1 Not used (0) 
0 (On if there are floppy disks. Bit must be on for bits 6 and 7 to 
be valid. 
VidMode 
Name: VidMode 
‘Type: Procedure 


Purpose: To determine information about the current video mode 
Calling Sequence: UidHode(Mode, Textliidth, Page) 








Description 
‘The VidMode subprogram uses a ROM BIOS video service to retrieve information 
about the video mode currently in effect. With this information, you can adapt your 
programs to take appropriate action depending on whether you are running them 
(on a color/graphics or monochrome video screen, in graphics mode or text mode, 
in black-and-white or color, using page 0 or not, or with a text-line length of 40 
or 80 characters. 
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Input 
None 


Output 


Node byte A number from 0 through 15 that indicates the 
current video display mode. Modes 0 through 6 are 
for the Color/Graphics Adapter (CGA), 7 is for the 
Monochrome Adapter, 8 through 10 are for the PGjr, 
and 13 through 15 are for the Enhanced Color/ 
Graphics Adapter (EGA). See table 15.2 in the 
Discussion section for details 

Textliidth byte The text-line width of the current video display 
mode (20, 40, or 80) 


Page byte The current active page number in use (0 through 3 
for 80-column text widths, or 0 through 7 for color/ 
graphics in 40-column width), Turbo Pascal normally 
luses page 0 at all times. 


Limitations and Error Conditions 


Turbo Pascal does not provide commands for setting the video mode to all the 
possible settings indicated here. Table 15.2 shows the Turbo commands for setting 
standard video modes with the Monochrome and Color/Graphics Adapters. Acti- 
vating the modes that have no Turbo command indicated may require some fancy 
footwork (assembler language interface, direct memory access, etc.). AS new video 
interfaces are created, other Mode values may be added. 


Sample Usage 
program SampleUsage0fUi dade; 


var 
Node, TextUldth, Page: byte; 


($1 Vidtode, PSL? 
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BEGIN 
Vidtlode(Mode, Textllidth, Page); 
uriteln(’Hode*’, Mode, ‘ Uidth”, TextUidth, “ Page=’, Page); 
dolay (5208); 


graphnode; 
UidHoda(Hode, Textllidth, Page); 
uriteln( Mode’, Mode, “ Widthe", Texthiidth, “ Pager’, Page); 
delay (508); 
‘textaode 
END. 


When you run this sample program with an 80-column, black-and-white monitor 
attached to the Color/Graphics Adapter, the program displays the first line shown 
in the following sample output and then waits five seconds, clears the screen, and 
displays the second line in large (40-column ) characters. (‘The graphaode command 
‘causes the screen to be cleared and enables the subsequent generation of the large 
characters.) If the program is run with the Monochrome Adapter, the three output 
values are instead 7, 80, and 0 both times. 


Mode=2 Width=88 Page 
Mode*5 Uidth=4@ Pages® 


Subprogram Listing of VidMode.PSL 
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Variables 


‘The standard internal registers used in passing data to and 
from Turbos msdos procedure 





Discussion 
Table 15.2 shows the Mode values returned as a result of Turbo's various graphics 
and text mode commands for activating the standard modes, 











Table 15.2 
Interpretation of the Hode Value 
Mode Turbo Display Adapter Length 
Command Type and Height 
° textmode(bu4@) bw text 40, 25 
1 textmode’ cd) color text 40, 25 
2 textmode(bue®) bw text 80, 25 
3 textmode( 80) color text 80, 25 
4 graphcolormode color graphics 320, 200 
5 graphnode bw graphics 320, 200 
6 hires bw graphics CGA 640, 200 
ch textnode bw text mono 80, 25 
8 color graphics PGir 160, 200 
9 color graphics PGjr 320, 200 
10 color graphics PGjr, EGA 640, 200 
13 color graphics EGA 320, 200 
4 color graphics EGA 640, 200 
5 color graphics EGA 640, 350 





Although Page is always zero when you use standard Turbo Pascal commands, you 
‘can use other pages through other languages (assembler subroutines, for example). 
‘We have experimented in trying to cause Turbo to use other video pages (by 
changing the active page through another ROM BIOS service), but Turbo insists 
‘on using page zero all the time for its standard graphics and text output. Apparently 
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‘you must manipulate memory locations in order to make effective use of other 
pages in Turbo. Despite this limitation, we include Page in this subprogram because 
of the parameter’s potential usefulness with subroutines in other languages. 

Modifications 


‘None 


VideoChg 
Name: VideoChg 
Type: Procedure 


Purpose: To change between monochrome and color/grapbics video 
screens or determine which screen is in use 


Calling Sequence: Vi deoChg(Uhi chi deo) 














Description 


“Turbo Pascal has plenty of extensions for the IBM PC so that you can switch between 
text and graphics modes, but Turbo provides no way to switch between the two 
physical video monitors you can have on your computer. (The graphics commands 
are based on the assumption that you are currently using the Color/Graphics Adap- 
ter.) If you have an IBM PC with both the Monochrome Adapter and the Color/ 
Graphics Adapter, this subprogram enables you to switch from one to the other 
while your Turbo Pascal program is running, You do not need to stop your program, 
‘use the PC DOS or MS-DOS MODE command to switch to the other monitor, and 
then restart your program. Vi deoChg also has an option to determine which of the 
two screens is currently being used. Before issuing any graphics commands, you 
should find out whether the computer has the capability of performing graphics 
If the Monochrome Adapter is currently in use, you cannot perform graphics. 


Input 

UhichVideo char A single character that indicates the action you want 
VideoChg to perform. If the character is M or , you 
want to switch to the Monochrome Adapter. If the 
character is C or ¢, you want to switch to the Color/ 
Graphics Adapter. If Uhi chVideo is any other 
character, you want to find out which video adapter 
is currently in use. 


466 ‘TURBO PASCAL PROGRAM LIBRARY. 





Output 
UhichVideo char If the character you pass to VideoChg is something 
other than H, @, C, or c, then UhichVideo is changed 
to M or C, depending on whether the current video 
adapter is Monochrome or Color/Graphics, 
respectively. Otherwise, Uhi chUideo is changed to E 
(error) if you try to switch to a video display you 
don't have installed, or unchanged if the switch is 
successfully made. 
In addition, if you specify M, a, C, or 6, and you have the appropriate video adapter 
installed, that video adapter becomes the active one. The previous video screen is 
not cleared (blanked) unless you clear it yourself with Turbo's clrser procedure 
before you use VideoChg. However, the new video screen (that you are switching. 
to) is cleared by UideoChg, 





Limitations and Error Conditions 


The subprogram sets your Color/Graphics Adapter to 80-column mode in black 
and white. This is the same mode that results from the DOS command MODE BW80, 
You can switch to 40-column mode and/or color mode with Turbo's textmode 
procedure after you use UideoChg 


‘There is a complication in using this subprogram during program development 
‘Turbo Pascal apparently checks to see which video adapter is in use only when 
Turbo starts up. If you use VideoChg to switch to the other adapter, Turbo does 
ot recheck which video screen to use after you compile and run your program. 
‘Turbo continues to write to the old screen, even though some system information 
ls changed by VideoChg, making such output impossible. The result is that neither 
screen is properly used by Turbo from then on. 


You can deal with this complication in two ways. One approach is to press the Q 
key to quit Turbo at that point and then restart Turbo, using the new screen. Be 
sure that you remember to use option S to save your source program before running 
it. (This advice is always sound. ) The other approach is to design your test program 
so that it switches back to the original screen before ending. In this case, you can 
continue using Turbo with no problems. 


‘This subprogram was tested on a standard IBM PC with both standard video adap- 
ters. Whether UideoChg works on other “compatible” computers and adapters d 
pends on just how compatible they are. Be aware that some hardware technicians 
recommend against having both video displays in use at the sume time. Check with 
your computer manufacturer or dealer to be sure 
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Sample Usage 
program SampleUsage0fUi deoChg; 


var 
UntchUideo: char; 


{$1 VidaoChg. PSL) 


BEGIN 
UnichVideo == “x; 
UideoChg (thi chUi deo); 
write’ Current video is“); 
case UhichVideo of 
“Ms writeln( monochrome’ ); 
“0: uriteln(’ color/graphics’ ) 





else 
gin 
writeln(’** error - recheck your typing **” ); 
exit 
end 
end; 
uriteln(’ Switching to your second video after 5 seconds’ ); 
dolay (5008); 
clrser; 


If UnichUideo = “MH” then 
UnichYideo «= ‘C’ 








else 
UnichVideo «= “H; 
UideoChg (thi chi deo); 
if WnichVideo = “E’ then 
begin 
uriteln(’** Error - video adapter not available +), 
halt 


end; 
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uriteln(’Now using your second video’ ); 
weltaln( Sottching back ta, your, first wides after 5 seconds; 
Af UnichVideo = “Ht then 
UbichUideo 
else 
UhichUideo «= “MH; 
delay (5808); 
clescr; 
UideoChg (Uh! chUi deo); 
writeln(’ Now back on your first video ) 





c 


‘This sample program indicates the type of video display currently in use, waits five 
seconds, nd attempts to switch to the other video display. Ifthe other video display 
is not installed, the program displays an error message and stops. If the switch is 
successful, the program displays a message on the second display, waits five seconds, 
‘and switches back to the original display. In each case, the program clears the video 
display screen just before leaving it. (U1deoChg automatically clears the new screen 
‘it switches to.) 


Subprogram Listing of VideoChg.PSL 
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Variables 
Reg 
Uideodk 


ColorSeg 
ColorOfs 
HonoSeg 
MonoDf s 


Testa 
Tost 


Discussion 


A record of integer variables representing the 
microprocessor’s registers and flags. Reg is used to pass 
values to Turbo’s intr procedure. 


boolean variable that is set to true if the video screen to 
be switched to exists, but false if it does not exist 


Segment address of the color/graphics screen area 
Offset address of the byte tested in the color screen area 
Segment address of the monochrome screen area 


Offset address of the byte tested in the monochrome 
screen area 


‘The first test value that is placed in the screen area in 
order to test whether the screen is installed 


‘The second test value 


‘We tried to use a method that would make this subprogram not only easy to un- 
derstand but also less likely to become obsolete because of hardware and software 
developments from IBM and other vendors. Time will tell whether we guessed 
right. The subprogram tests whether the new screen (you want to switch to) is 
installed by putting a value into the screen's memory area and then checking 
whether the value actually stays there (thus verifying that the screen's memory arca 
exists). Ifthe value doesn’t stay, you don’t have the adapter installed for that screen, 
and UhichUideo is set to E to indicate an error. The screen-memory test is done 
‘twice, with different values, to ensure that the first value is not coincidentally the 
value obtained when the subprogram tries to access nonexistent memory. 
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If the other screen exists on your system, the subprogram modifies a location (hex 
410) in the data area that is used by the PC’s ROM-resident BIOS (Basic Input/ 
Output System) in order to indicate the equipment attached to your computer. 
‘The subprogram changes the necessary bits (in location hex 410) to reflect the 
video mode you want and then invokes the ROM BIOS video service interrupt (hex 
10), using service 0 to set the video mode. The BIOS routine does the work to 
‘switch to the monitor you select, and the change is reflected in another BIOS data 
location (hex 449). We use this location to check which video adapter is currently 
in use, 


Modification 


You can revise the subprogram so that it clears the old video screen just before 
you switch to the new one. This change eliminates the need for your main program 
to clear the screen just before calling VideoChg cach time (assuming that clearing 
the screen is what you want to do). Add a new line following cach of the two 
lines indicated by (Mod. #1) in the subprogram. Each new line should be simply 


elrser; 
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Handling Errors 





Turbo Pascal has limited facilities for handling error conditions while a program 
is running, but this chapter has two subprograms that deal with errors. IGError 
simplifies the task of checking for errors after 1/O operations. RunError intercepts 
run-time errors and displays informative messages instead of mysterious error code 
numbers 


IOError 





Name: [OBrror 
‘Type: byte function 

Purpose: To perform error checking after an 1/0 operation 
Calling Sequence: I0Error 











Description 

If the default ($14) (1/0 error handling) compiler directive is in effect, Turbo 
Pascal aborts a program if any 1/O error condition occurs. Such drastic action is 
‘often unwanted, for instance, when a program is trying to open a disk file that is 
not found. A better programming approach is to inactivate the I/O error-handling 
compiler directive with ($1~) and have the program check whether the file open 
is successful. Ifthe open is not successful, the program can display an error message 
and ask for a new file name. This subprogram does some of the work in checking 
for error conditions by displaying a brief error message for any known 1/O error. 
‘The main program must then determine the action to take. 


Input 
I0Error has no input variables, but the 1/O error-handling compiler directive must 


be inactive (€($1-)) in order for Turbo's ioresult to be set after an 1/O operation. 
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Output 


Error byte The function 10Error returns the numeric error code 
obtained from loresult, If Error is zero, no error 
occurred. The error codes are explained in Appendix 
G of the Turbo manual. 


In addition, the subprogram beeps and displays a general 1/O error message at the 
current cursor position, then a message with the error code in decimal, and then 
4 message for the particular type of I/O error that occurred. 


Limitations and Error Conditions 


If toresult does not contain either zero or any of the error numbers listed in 
Appendix G of the Turbo manual, the error type is displayed as “unknown 1/O 
error type” on the sereen. Note that loresult must be examined after every 1/0 
‘operation, either by I0Error or by your main program, so that error conditions 
can be handled, 





Sample Usage 
program SamplaUsageOf 10Error; 


var 
Code byte; 
File = text; 
TextLine © stringt255J, 


($1 10€rror, PSL) 


BEGIN 

(sI-) 

assign(FileA, ’NONEXIST. ENT’), 

Code =» 10Error; 

if Code © @ then 

begin 

uriteln(’ Error in assign statement’ ); 
halt 


‘end, 
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reset (FileA); 
Code : 10Error; 
if Code © @ then 
begin 
uriteln(’ Error in reset statenent’ ); 
halt 
end; 
readin(FileA, TextLine), 





jin 
writeln(’ Error in readin statement’ ); 
halt 


end; 
close(FileA); 
Coda =* 10Error; 
1f Code © @ then 


begin 
writeln(’ Error in close statement’); 
halt 


end 
END. 


‘This sample program demonstrates how to use 10Error after disk 1/0 operations. 
‘The program tries to open a file that doesn't exist on disk. Note that the assign 
statement doesn’t cause the error, but the subsequent reset docs. 





** 1/0 error encountered. 

© error code = 1 (decimal) 
no such filenase in directory 
Error in reset statenent 


Subprogram Listing of |OError.PSL 





‘TURBO PASCAL PROGRAM LIBRARY, 


V/O error code retrieved from Turbo's toresult 
Msg Error message for the error code 


Discussion 


If you choose not to do your own I/O error checking (either with this subprogram 
or with your own toresult checking), then 1/O errors are handled like any other 
run-time error As a result, /O errors may be either detected by the RunError 
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subprogram or left undetected to cause normal run-time errors. If you are the only 
one using your programs, error handling may not be especially important. If, how- 
ever, you write programs for others to use, error handling should occupy a large 
part of your programming efforts. Displaying cryptic error messages and aborting 
4 program abruptly are Wo signs of unprofessional programming. 

Modification 
Replace the indicated line with a halt statement to make the subprogram end for 
any 1/O error condition. This change is not recommended for polished programs, 
but it is a handy way to expedite program development by postponing the need 


to add error-handling logic to your main program until you have the program 
working. 


RunError 
Name: RunError 
‘Type: Procedure 


Purpose: To intercept runtime errors and display informative 
messages before aborting, 


Calling Sequence: errorptr °* of s(RunError) 








Description 


Run€rror can be activated to take control in the event of a run-time error (such 
as division by zero or an illegal string length). Unfortunately, Turbo Pascal provides 
‘no means of recovering from the error and continuing with the program. Instead, 
you can only display informative messages and let Turbo cither continue with 
regular abort actions (as this subprogram does) o come to a more graceful, “nor- 
mal” end. (Sce the Modification section.) Even with these limitations, a program 
for distribution to others (and one that is prone to certain types of run-time errors) 
can be made more understandable and usable if you incorporate this subprogram 
or something like it 











Input 


RunError requires no input variables (the two parameters shown on the procedure 
statement are passed by Turbo, not your program), but the subprogram must be 
activated by the following statement 
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rorptr == ofs(RunError); 


(For 8bit versions of Turbo, replace of s with addr.) This statement puts the address 
Of the error-handling subprogram into the reserved location called errorptr. 


Output 


No output variables are changed. The subprogram displays two error messages. The 
first message indicates the type of error that occurred (user-interrupt error, /O 
error, run-time error, or unknown error). The second message is displayed only if 
the error is a run-time error. This message specifies the type of error that took 
place. After one or both messages are displayed, the subprogram attempts to return 
control to the main program through an exit statement. Because Turbo does not 
allow the main program to continue, the result is that Turbo takes contro! and 
performs its regular run-time error handling, If you are running the program in 
memory mode, Turbo displays its normal error messages and searches through your 
source code for the statement that caused the error, 





Limitations and Error Conditions 


The error messages are displayed beginning at the current cursor location. If the 
error code does not match one of the codes in Appendix F of the Turbo manual, 
the second message calls the error an “unknown run-time error type. 


Sample Usage 
program Sanp|oUsageOfRunError; 
type 
Caps = A.2; 
var 
X real, 
J integer; 
Str © stringl2553, 
Allph « Caps; 


($1 RunError. PSL) 
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errorptr *= ofs(Runérror' 
(The following statements all cause run-time errors.) 
X s= 10635, for J == 1 to 18 do X == X* XK, 








Str(@] := #200, Str == Str + Str; 
Str += copy(str, 8, 1); 
StrfJ] = 10, 





‘This sample program has a series of lines that can cause various run-time efrors. 
‘The first line of this series causes a fatal error, as shown in the sample output that 
follows. To see the effect of the next error, either delete the line that causes the 
first error or surround that line with braces, thus turning it into a comment. Then 
rerun the program to get the next error. Note that the CRF) statement at the 
beginning of the sample program is not needed by RunEr ror. The statement is there 
only to force a run-time error later in the program. Running this sample program 
produces the following output: 


#* Error — Run-time error caused by 
© floating point overflow 


‘At this point, Turbo takes over to abort the program. 


Subprogram Listing of RunError.PSL 
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Variables 
Errortat ‘The error category (0 = user interrupt, 1 = 1/0 error, 
2 = run-time error, other = unknown) 
ErrorNun ‘The run-time error number, as listed in Appendix F of the 
‘Turbo manual 
Msg ‘An error message that corresponds to the error number 
Discussion 


If you encounter an 1/O error in a program that has activated RunError, the error 
causes RunError to get control only if ($1+) is in effect. (See I0Error.) If ($1- 
is in effect, your program is doing its own error handling instead (cither by checking, 
joresult itself or by using a subprogram like I0Error ). RunError is not designed 
to give details about an I/O error (I0Error does that), but docs display a message 
indicating that an 1/O error has occurred. 
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Modification 
Replace exit with halt in the two indicated lines, causing the program to come 
to a normal end instead of forcing Turbo to invoke its abort actions, See the Output 
section for details. 
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if 


Manipulating Times and Dates 








‘Turbo Pascal has a built-in delay procedure that causes a program to pause for a 
specified amount of time. Nothing else relating to times and dates is available, 
however. Because many programs must work with times and dates, this chapter 
contains 10 subprograms for that purpose. Internal clocks and calendars vary among 
different computers; therefore, most of these subprograms are based on the ca- 
pabilities of PC DOS (or MS-DOS) and the IBM PC, and most of the subprograms 
make use of Turbo's msdos facility 


Four subprograms deal with the computer's time of day. GetTime retrieves the 
‘current time of day from the computer's internal clock. ShouTime displays the cur- 
rent time of day in a standardized form. SetTime sets the current time to the time 
‘you specify. Finally, TimeDiff calculates in seconds the elapsed time between two 
times, 


‘Three subprograms are date-oriented counterparts of the first three time subpro- 
grams, GetDate retrieves the current date, ShouDate displays the current date, and 
SetDate sets the current date. The remaining three subprograms also deal with 
dates but are independent of PC DOS and the IBM PC. Jul ian converts a date into 
the corresponding Julian day number, which is useful for computing differences 
between dates. JulToYMD converts a Julian day number to year-month-day form. 
Finally, DaylJeek determines the day of the week (Sunday through Saturday) on 
which a date falls. 


GetTime 





Name: GetTime 
‘Type: Procedure 
Purpose: To retrieve the current time of day in numeric form 
Calling Sequence: GetTiveCHr, Min, See, Hun) 
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Description 
GetTine uses DOS function call hex 2C to retrieve the current time of day in 
numeric form. After retrieving the time, your calling program can display it (or 
use ShouTime), calculate elapsed times (see TineDiff), time-stamp events that are 
recorded in a disk file, and even act as an alarm clock. 


Input 
None 
Output 
He byte The hours portion of the time of day (0-23) 
Min byte The minutes portion (0-59) 
See byte ‘The seconds portion (0-59) 
Hun byte The hundredths-of.asecond portion (0-99) 


Limitations and Error Conditions 


‘The IBM PC's internal clock is updated about 18.2 times per second (actually 
18,206482), or about once every .055 seconds (actually 0549255). Even though 
you can invoke GetTime many times in .055 seconds, the time of day remains the 
same until the next tick of the clock adds another .055 seconds. In practice, the 
time increases by either .05 or .06 seconds (depending on rounding) even though 
the clock appears to have .0L-seconds resolution, Thus, for accuracy, rounding times 
to the nearest one-tenth of a second is recommended. 





Sample Usage 
Program SampleUsage0fGetTime; 


var 
Hr, Min, Sec, Hun’ byte; 


(SI GetTime. PSL) 


BEGIN 

GetTime(Hr, Min, Sec, Hun); 

uriteln(’ The time 15’, Hr, °°", Min, °-", Sec, “.”, Hun-2) 
END. 
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‘The sample program displays the current time of day in a simple form, without 
leading zeros for each portion. The hundredths portion, if less than 10, has a leading 
space. Note that the 24-hour form is used. To convert to p.m, you subtract 12 


from the hours portion when that portion is greater than 12. The time shown is 
2.51 seconds after 6:57 p.m: 


The time 1s 18:57:2 51 


Subprogram Listing of GetTime.PSL 





Variables 
Reg “The standard internal registers used in passing data to and. 
from Turbo's msdos procedure 
Discussion 
None 
Modifications 
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ShowTime 


Name: ShowTime 
Type: Procedure 
Purpose: To display the current time of day on the screen 
Calling Sequence: ShouTine 











Description 
ShouT ime retrieves the current internal time and uses a wri teln statement to display 
the time on the screen. All components are displayed with two digits. (That is, a 
zero precedes each component that would otherwise be a single digit.) Colons 
separate hours, minutes, and seconds. A decimal point separates seconds and hun- 
dredths of a second. 

Input 


None 


Output 
‘The current time of day is displayed as an 11-byte string at the existing cursor 
location. The cursor moves to the beginning of the next line after the time is 
displayed. 
Limitations and Error Conditions 
See the clock-resolution limitations explained in GetTine. 
Sample Usage 
program SanpleUsage0fShouT ine; 
(SI ShouTime. PSL? 
BEGIN 
urite(’The time is“); 


ShouTime 
END. 
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The sample program displays the current time of day: 


The time is 18: 


Subprogram Listing of ShowTime.PSL 





Variables 


Hin 
Sec 





06. 08 


‘Twodbyte string of current hour, permitting a leading zero 
to be added, if necessary 


‘Two-byte string of current minute 
‘Two-byte string of current second 
‘Two byte string of current hundredths of a second 


‘The standard internal registers used in passing data to and 
from Turbo's asdos procedure 
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Discussion 


None 


Modifications 
1. To eliminate the leading zero before the time's hour component, delete 


the line indicated by (Hod. #1. This change causes a leading space to be 
displayed when the hour is 0 (zero) through 9. 


‘To change the form in which the time is displayed, alter the indicated 
writen statement. For example, if you want only the hour and the 
minute to be displayed, change the statement to 


writeln(He, “7, Mind 


‘You may want to change writeln to write. This prevents ShouTime from 
moving the cursor to the beginning of the next line after displaying the 
time. 


SetTime 
Name: SetTime 
‘Type: Procedure 


Purpose: To set the computer's internal clock to a specified time 
Calling Sequence: SetTime(Hr, Hin, Sec, Hun) 








Description 


SetTime uses DOS function call hex 2D to set the internal clock to the time you 
specify. Some programs require an accurate clock setting; this subprogram provides 
a means of forcing the user to enter the correct time. (Users sometimes get lazy 
and skip the time-entry procedure during the boot process.) 


Input 
Hr byte The hours portion of the time of day (0-23) 
Min byte The minutes portion (0-59) 
Sec byte The seconds portion (0-59) 


Hun byte The hundredths-of.2-second portion (0-99) 
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Output 


‘The time-of-day clock in the computer is set to the specified time. If illegal values 
are specified, Hr is set to 25. 


Limitations and Error Conditions 


‘The four specified values (Hr, Hin, Sec, and Hun) must be set to legal values, as 
shown in the Input section. If any value is not legal, Hr is set to 25 to indicate an 
error. 


Sample Usage 
program Samp|eUsage0fSetTime; 


var 
Hr, Min, Sec, Hun: byte; 


{$1 SotTime. PSL) 
(SI ShouTime, PSL) 


BEGIN 
Hr i= 14; 
Min o= 
Sec '= 8, 
Hun ‘= 8, 
SetTimatHr, Min, Sac, Hun); 
if Hr > 24 then 
writeln(’ ** Error - illegal time **’) 
else 
begin 
write’ The new time 1s“); 
ShouTime 
end 








‘The sample program sets the internal clock to 14:35 (2:35 p.m.) and then im 
mediately displays the new time. Note that such time settings are not always precise. 
Running the program produces the following output 


The now time 1s 14:34:59. 98 
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Subprogram Listing of SetTime.PSL 





Variables 


Rog The standard internal registers used in passing data to and 
from Turbo's asdos procedure 


Discussion 
None 

Modifications 
None 

TimeDiff 


Name: TimeDiff 
‘Type: real function 
Purpose: To calculate the number of seconds between two times 
Calling Sequence: TimaDiff (Hr, Min, Sec, Hun, Hr2, Min2, See2, Hun2) 








MANIPULATING TIMES AND DATES 491 





Description 


‘This subprogram calculates the number of seconds between two times of day, which 
are in the same form used in other subprograms in this chapter. The times can be 
‘obtained from the GetTime subprogram, in which case TimeDiff calculates the 
lapsed time between two real-time events. Or the times can come from any other 
source, as long as they are converted to the form shown here, 





Input 

Hr byte The first time's hours 

Min byte The first time’s minutes 

See byte The first time's seconds 

Hun byte The first time’s hundredths of seconds 

Hr2 byte The second time’s hours 

Mind byte The second time’s minutes 

Sec? byte The second time’s seconds 

Hun byte The second time's hundredths of seconds 
Output 

TimeDiff real The function TimeDiff returns a real value that is 


the number of seconds between the two times (with 
two decimal places). If TimeDiff is negative, the 
second time is earlier (smaller) than the first. For 
details, see the next section. 


Limitations and Error Conditions 


{As discussed in GetTine, the resolution of the IBM PC clock is about .055 seconds. 
If the PC's timer is the source of the two times, TimeDi ff can be no more accurate 
than the timer, even though two decimal places are carried in the result. The 
arithmetic is accurate to two decimal places. 


If the calculated time difference is negative, the second time is carlier (smaller) 
than the first because of one of two reasons. Either you did not know which time 
‘would be earlier (or you accidentally reversed them), or midnight took place be: 
tween the two times. In the first case, if you know that both times are from the 
same day, you can simply take the absolute value of TimeDiff (using Turbo's abs 
function) to get the correct answer. In the second case, you can add 86400.0 (the 
number of seconds in 24 hours) to TimeDi ff. The Sample Usage program contains 
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an example of two times, with midnight between them. The values passed to 
TimeD! ff are not required to fall within the normal ranges. (For instance, Min does 
not need to be in the 0-59 range.) Sixty-five minutes is treated as 1 hour and 5 
minutes. Because all values are defined as byte, however, each value must be from 
0 to 255. 


Sample Usage 
program SamplaUsage(fTimeDi ff; 


var 
Hr, Min, Sec, Hun, Hr2, Min2, Sec2, Hun2> byte; 
Seconds: real; 


(SI TimeDiff. PSL) 
(SI GotTime, PSL) 


‘BEGIN 
GetTime(Hr, Min, Sec, Hun); 
delay 1000), 
GetTime(Hr2, Min2, Sec2, Hun2); 
Seconds «= TimeDiff(Hr, Min, Sec, Hun, Hr2, Min2, Sec2, Hun2); 
writeln(’End time =‘, Hr2:2, Min2*3, Sec2'3, Hun2'3); 
writeln(’ Start time =’, He'2, Mins3, Sec'3, Hun'3); 
writeln(’ Time difference =, Seconds'7'2, ° seconds’ ); 
Hr i= 23; Min 1= 59, Sec == 54; Hun «= @ 
Hr2 «= 8; Mind '= Sec2 = 7, Hun2 ‘= 8 
Seconds TimeDiff(Hr, Min, Sec, Hun, Hr2, Min2, Sec2, Hun2); 
if Seconds ¢ 8.8 then 
Seconds «= Seconds + 86408. 0; 
writeln(’ Second time difference =‘, Seconds 6'2, ‘ seconds’) 
END. 











This sample program produces two results that illustrate two different points. The 
first result tests the accuracy of Turbo's delay procedure using the PC's internal 
clock, The Turbo manual warns that the exact delay may vary in different operating 
environments. Our experience is that delay pauses about 6 or 7 percent less than 
the delay indicated by the PC clock. You can experiment on your system by changing 
the number in the delay statement. The first time difference should be 1.00 seconds 
for a 1,000 millisecond delay. Try 10,000 milliseconds (10 seconds) also. The 
coding for the second time difference shows how to handle a case in which you 
know that the second time should be later than the first, but midnight may intervene. 
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Note that the sample program makes use of GetTine to get the current time of 
day. Thus, GetTime. PSL is required on your default disk drive for this sample pro- 
gram. Running the program produces the following output: 





End time = 14 23 19 38 

Start time = 14 23 18 45 

Time difference = @.92 seconds 
Second tine difference = 13.00 seconds 


Subprogram Listing of TimeDiff.PSL 





Variables 


None 


Discussion 


‘You can use many tricky ways to subtract one time from another. This subprogram 
uses a straightforward method: simply convert each time into the number of seconds 
that have elapsed since midnight, and then subtract one time from the other 


Modifications 


None 


GetDate 
Name: GetDate 
‘Type: Procedure 
Purpose: To retrieve the current date in numeric form 
Calling Sequence: GetDate(Yr, Hon, Day) 
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Description 
GetDate uses DOS function call hex 2A to retrieve the current date in numeric 
form, After retrieving the date, the calling program can display it (or use ShouDlate ), 


calculate date differences (see Julian), date-stamp events that are recorded in a 
disk file, and so on. 


Input 
None 
Output 
Yr byte The year portion of the date (0-99) 
Hon byte The month portion (1-12) 
Day byte The day portion (1-31) 


Limitations and Error Conditions 


‘The year (Yr) is returned as a 2-digit number. The years 1980 through 1999 are 
returned as 80 through 99. The years 2000 through 2079 are returned as 0 through 
79. ‘The years 2080 through 2099 are returned also as 80 through 99. 


Sample Usage 
Program Samp] eUsageOfGetDate; 


var 
Yr, Mon, Day: byte; 


(SI GetDate. PSL) 


BEGIN 

GetDatetYr, Hon, Day); 

uriteln(’ The date is‘, Yr, “~", Mon, *~", Day) 
END, 


The sample program displays the current date in a simple form (year-month-day) 
without leading zeros for each portion: 


The 3 86-2-27 
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Subprogram Listing of GetDate.PSL 





Variables 
Reg ‘The standard internal registers used in passing data to and 
from Turbos asdos procedure 
Discussion 
None 
Modifications 


496 TURBO PASCAL PROGRAM LIBRARY 





ShowDate 


Name: ShowDate 
‘Type: Procedure 
Purpose: To display the current date on the screen 
Calling Sequence: Shoslate 











Description 
ShouDate retrieves the current internal date and uses a uriteln statement to display 
the date on the screen. The date is displayed in year-month-day form, A leading 
zero precedes each single-digit component, and the components are separated by 
hyphens. You can easily change the form with a modification that is provided, 
Input 


None 


Output 


‘The current date is displayed as an cight-byte string at the existing cursor location. 
‘The cursor moves to the beginning of the next line after the date is displayed. 





Limitations and Error Conditions 
‘The year is converted to a two-digit number, as explained in GetDate. 
Sample Usage 
program SampleUsage0fShouDate; 
(51 ShouDate, PSL) 


BEGIN 
urite( The date is“); 
Shoullate 

END. 


‘The sample program displays the current date in year-month-day form: 


The date 1s 86-86-13 
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Variables 
Yr 


Subprogram Listing of ShowDate.PSL 


‘The year in two-byte string form, permitting addition of a 
leading zero, if necessary 


Two-byte string of the month 
‘Two-byte string of the day 


‘The standard internal registers used in passing data to and 
from Turbo's asdos procedure 
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Modification 
To change the form in which the date is displayed, alter the line indicated by 


(Mod. #1). Change the year-month-day form into month/day/year form by using the 
statement 


—— 
uriteln(Hon, “/’, Day, °/’, Yr) 


SetDate 





Name: SetDate 
‘Type: Procedure 
Purpose: To set the computer's internal date 
Calling Sequence: SetDate(r, Mon, Day) 











Description 
SetDate uses DOS function call hex 2B to set the internal date to the date you 
specify. Some programs require an accurate date setting; this subprogram provides 
4 means of forcing the user to enter the current date. (Lisers sometimes get lazy 
and skip the date-entry procedure during the boot process.) 


Input 
Yr byte ‘The year portion of the date (0-199) 
ton byte The month portion (1-12) 
Day byte The day portion (1-31) 

Output 


The internal date in the computer is set to the date specified. If illegal values are 
specified, Yr, Hon, and Day are all set to zero, 


Limitations and Error Conditions 


The three specified values (Yr, Hon, and Day) must be set to legal values, as shown 
in the Input section. If the values are not legal, all three values are set to zero to 
indicate an error. The Yr values of 80 through 99 are interpreted as 1980 through 
1999, For 0 through 79 (or 100 through 179), the interpretation is 2000 through 
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2079. For 180 through 199, the year is set to 2080 through 2099. DOS does not 
allow the current year to be earlier than 1980. 


Sample Usage 
program SanpleUsage0fSetDate; 


var 
Yr, Mon, Day: byte; 


($1 SetDate. PSL) 
($1 ShowDate. PSL) 


‘BEGIN 
Ye += 8, 
Mon += 12; 
Day = St; 
SetDatetYr, Hon, Day); 
f Hon = @ then 
uriteln(’** Error — illegal date **) 
else 


begin 
write(’ The new date ts"); 
ShouDate 


‘The sample program sets the internal date to December 31, 1987, and displays the 
new date immediately afterward: 


The new date 1s 87-12-31 


Subprogram Listing of SetDate.PSL 
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Reg ‘The standard internal registers used in passing data to and 
from Turbo's msdos procedure 
Discussion 
None 
Modifications 
None 
Julian 
Name: Julian 
‘Type: real function 
Purpose: To calculate the Julian day number for a given year, 
‘month, and day 
Calling Sequence: Jul tan(Year, Hon, Day) 
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Description 


‘This subprogram calculates the day number within the Julian period for the specified 
year, month, and day. The Julian day number is commonly used by astronomers to 
indicate the dates of astronomical events. The number is also useful to computer 
programmers in determining the number of days between two dates. The start of 
the Julian period was January 1, 4713 B.C, as determined by the Julian calendar. 
‘The starting point for the current Gregorian calendar is a date that is a few weeks 
away from that. See the Limitations and Error Conditions section and the Discussion 
section for details. 


Input 
Year Integer The year portion of the date, (See Limitations and 
Error Conditions.) 
Mon byte The month portion (1-12) 
Day byte The day portion (1-31) 
Output 
Julian real The function Julian returns the day number within 


the Julian period for the date provided. 


Limitations and Error Conditions 


If Mon or Day is out of the range shown in the Input section, or if Year is negative, 
ul tan is set to -1.0 to indicate an error. When Year is from 0 (zero) t0 99, it is 
assumed to mean 1900 through 1999. Note that Year in this subprogram is defined 
as an integer variable, whereas Yr is defined as a byte variable in the previous 
date subprograms. As used by astronomers, the Julian day begins at noon. Thus, 
each night's astronomical observations occur on one day, without the date changing 
at midnight. The day number calculated by this subprogram is the day beginning 
at noon on the date specified 


‘The algorithm used for this subprogram provides a valid result for any Gregorian 
calendar date that produces a Julian day number greater than zero. Julian day num- 
ber 1 corresponds to the Gregorian date November 25, 4714 B.C, or November 
25 of year -4713. The difference occurs because the Gregorian calendar has no 
year 0 (zero) between 1 BC. and AD. 1, but the Julian period requires a zero year 
between years -1 and 1. Even though ancient dates are technically valid, be aware 
that the English-speaking world converted to the Gregorian calendar on September 
14, 1752. Earlier dates produce correct results only if you provide the dates in 
Gregorian terms. 
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Sample Usage 
program Samp] eUsage0f Jul ian; 


var 
Year integer; 
Hon, Day » byte; 
NunDays « real; 


($1 Julian, PSL) 


BEGIN 
repeat 
writeln(’ Enter date’); 
write’ Year: ’); — read¢Year), 
uritet’ Month: *); read(Hon); 
write’ Day: read(Day); 
writeln, 
NunDays + Jultan¢Year, Mon, Day); 
if NunDays < @.@ then 
uriteln(’*® Illegal date #*) 
else 
writeln(’ Julian day =“, NunDays:8 
until NumDays ¢ 8.8 
END. 








The sample output that follows shows the Julian day for several dates. The sample 
Program continues until you enter an illegal date. 


Enter date 

Year: 1985 Month: 12 Day: 31 
Julian day = 2446431 
Enter date 

Year: 86 Month’ 1 Day: 1 
Julian day = 2946432 
Enter date 

Year: 1776 Month: 7 Day: 4 
Julian day = 2369916 
Enter date 

Year: 2000 Month: 2 Day: 29 
Julian day = 2451604 
Enter date 

Year: 0 Month: 0 Day: 0 

** Illegal date =» 
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Subprogram Listing of Julian.PSL 





Variables 
Tenp ‘A partial result, used in calculating the Julian day number 


Discussion 
‘The most frequent application of this subprogram is finding differences between 
two dates. Every modem Julian day number is a large positive integer; therefore, 
determining how many days elapse between two dates is a matter of simple sub- 
traction, even if the two dates are hundreds of years apart. If you have defined a 
real variable Daysfpart, you can use the following approach. Of course, you can 
remove the abs (absolute value) function to find out which date is earlier, if 
necessary. 


DaysApart <= abs(Julian(¥i, Mi, Di) - Julian(¥2, M2, D2)) 


Another use of this subprogram is to find the date that isn days in the future (or 
past) from a given date. Use Jul ian to get the Julian day of the given date, add or 
‘subtract n (as appropriate ), and then use the Jul ToYMD subprogram to convert back 
to year month-day form. 
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For details about calendar differences and the Julian period, see The World Almanac 
‘and Book of Facts (Newspaper Enterprise Association, 1985), Beware of the 1985 
edition, however, which contains an error in the sample Julian day for December 
31, 1984, The correct Julian day is 2,446,066. (The 1986 edition has a similar 
error. ) For a discussion of the origins of the Julian period, see Chapter 6 of Counting 
the Eons, by Isaac Asimov (Doubleday, 1983). 


Modification 


‘To eliminate the conversion of year numbers from 0 (zero) through 99 into 1900 
through 1999, delete entirely the second statement indicated by (Hod. #12. In the 
first indicated statement, delete only the portion that reads (Year ¢8) or. These 
changes open the valid Year range to-4713 (4714 B.C.) through A.D. 99, in addition 
to later dates, See the Limitations and Error Conditions section for a warning about 
dates before 1752. 


JulToYMD 
Name: JulToYMD 
Type: Procedure 


Purpose: To convert a Julian day number into yearmonthday form 
Calling Sequence: Jul ToMD(Jul anDay, Year, Hon, Day) 














Description 
JulToYMD converts a Julian day number into year-monthlay form of the Gregorian 


calendar. This subprogram is the inverse of Jul ian, which has details about cal- 
‘endars and the Julian period 


Input 
JultanDay real The Julian day number to be converted into 
year: month-day form 
Output 
Year integer The year portion of the date 
Mon byte The month portion (1-12) 





Day byte The day portion (1-31) 
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Limitations and Error Conditions 


JulianBay must be a positive integer value, but no error checking is done, The 
output values correspond to the Gregorian calendar, even for a date before the 
Gregorian calendar’s use. See Julian for more information. 


Sample Usage 
program SampleUsageOf Jul ToYMD; 


var 
Jullanfay © real; 
Year integer; 
Hon, Day « byte; 


($1 Jul ToYMD, PSL) 


BEGIN 
repeat 
urite(’ Enter Julian Day: *); 
eadin(Jul fanDay); 
ulToYMD(JultanDay, Year, Hon, Day); 
{f JulianDay > @.8 then 
uriteln( Date 1s“, Year 
until Julfanday ¢ 8.0 
END. 











“7, Mon, “7", Day) 


‘The sample output that follows converts Julian days into year-month-day form, Many 
of the same dates are used that were in the Jul {an sample run. The program ends 
‘when you enter a negative or zero Julian day. 


Enter Julian day: 2446431 
Date 1s 1965/12/31 

Enter Julian day: 2446432 
Date is 1986/1/1 

Enter Julian day: 2369916 
Date ts 1776/7/4 

Enter Julian day: 2451605 
Date 1s 2000/3/1 

Enter Julian day: 1 

Date is -4713/11/25 

Enter Julian day- 0 
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Subprogram Listing of JuIToYMD.PSL 





Variables 
TompA, TenpB Two work variables used during the calculations 


Discussion 
‘See the Discussion section of Julian. 


Modifications 
None 


eek 
Name: DayWeek 
‘Type: Procedure 
Purpose: To determine the day of the week for a given date 
Calling Sequence: Daylleck(Year, Hon, Day, DayNum, DayName) 
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Description 


‘The DayUeek subprogram uses a method called Zeller’s congruence to determine 
the day of the week for any date. The day is provided in both numeric form (zero 
through six for Sunday through Saturday) and string form (a thrce-character ab- 
breviation for each day) 


Input 
Year integer The year portion of the date, (See Limitations and 
Error Conditions.) 
Mon byte The month portion (1-12) 
Day byte The day portion (1-31) 
In addition, you must specify in your main program the following global type 
declaration: 
type 
String3 = stringl33, 
Output 
DayNun byte The numeric day of the week (0 = Sunday, 1 = 
Monday, etc.), DayNum is set to 9 if an illegal date is 
specified. 


DayName string The text day of the week, containing three 
‘characters, of which the first is capitalized (Sun, 
Mon, Tue, etc.). DayName is set to ERR if an illegal 
date is specified. 


Limitations and Error Conditions 


Hon and Day must be set to legal values, as shown in the Input section. Year must 
be positive. If any of these parameters is not within bounds, DayNum is set to 9, and 
DayNane is set to ERR If Year is 0 through 99, the year is interpreted as 1900 
through 1999. Note that English-speaking countries converted to the Gregorian 
calendar (our present calendar) in 1752. (Other countries converted at other times 
‘over a period of several hundred years.) An carlier date yields a day of the week 
that does not correspond to the calendar in use at the time. 
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Sample Usage 

program SamplaUsageOfDaylieek; 

type 
String = stringl3J; 

CG, 


integer, 
re eta DayNum = yt 
+ Strings; 


($1 Daylleok. PSL) 


BEGIN 
Year = 1986; 
Mon = 2 
Day += 27; 
Daylleek(Year, Mon, Day, DayNum, DayName); 
writeln(’ Feb 27, 1986 = DayNum ‘, DayNum, * or “, DayName); 
Daybosk(1941, 12, 7, DayNun, DayNasa); 
uriteln(” Dec 7, 1941, was ’, DayName) 


‘The sample program displays the day of the week for two dates: 


Feb 27, 1986 = DayNum 4 or Thu 
Dec 7, 1941, was Sun 


Subprogram Listing of DayWeek.PSL 
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Variables 
DayText 


Cent 
Yr 
Temp 


Discussion 


[A string constant that contains the text values for the 
seven days 


‘The century number of the year specified 
‘The year within the century (0-99) 


[An intermediate numeric variable that holds the modulus 
remainder for conversion to a positive byte value 


Zeller's congruence is discussed in several sources, including Problems for Com- 
(puter Solution by Fred Gruenberger and George Jaffray (Wiley & Sons, 1965), Once 
‘you calculate the numeric day of the week, it is a simple matter to look up the 
text equivalent in the DayText string table. Or you can look up a different text 
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name in your main program by using DayNua. In different programming cases, you 

may need the full name of the day (such as Sunday), or you may need only the 

first one or two letters of the name (to label a crowded graph axis, for example). 
Modifications 


None 


18 





Full Programs Constructed 
from Subprograms 





Here is where the concept of the Turbo Pascal Program Library really shines! A 
primary goal of this book is to show how easily you can incorporate our integrated 
subprograms into your main programs. Now is our chance. 


‘This chapter presents 10 complete Turbo programs that demonstrate the method 
in action. Each program uses several subprograms from the book. On disk, each 
‘subprogram is saved with the three-letter file extension , PSL (for Pascal Subprogram 
Library, the subprogram portion of this program library). A main program invokes 
‘one of the subprograms by using Turbo's ($1) include compiler directive, Early in 
the source listing of each full program is a series of these directives for reading 
the necessary subprograms from disk. A typical part of this section of code looks 
like the following: 








($1 GetReply. PSL) 
(SI Key2Arr. PSL) 
(SI MatHult, PSL 
(SI Uaitkey. PSL 


Syntax is critical to ensure that Turbo treats these as compiler directives and not 
ordinary comments. The ($1 part must appear with no intervening spaces. Then 
‘comes a space followed by the name of the subprogram to be read in from disk 
Don’t forget the PSL extension. (Capitalization is irrelevant in the subprogram 
name.) Finally, a right brace (2) terminates the compiler directive. See Appendix 
A for details about storing the subprogram library on disk 


An Overview of the Programs 
‘The complete programs represent a potpourri of applications. Each program uses 


at least five different subprograms. In all, about one-third of the subprograms in 
the book are used. 


su 


512 ‘TURBO PASCAL PROGRAM LIBRARY 





‘The program NewsWire displays moving “ticker tape” type messages on the screen. 
You enter the desired text, and your message continually scrolls right to left in a 
framed message box. This program is great for announcements, advertisements, or 
special messages. 

‘Two math programs analyze paired X-Y data for correlation. TryCurvs calculates 
particular nonlinear curve fits, and PolyFit calculates polynomial fits of arbitrary 
degree. Your data can be typed from the keyboard, saved on disk, and retrieved 
later. 

SortDir provides a display of a disk directory in alphabetical order. This program 
also displays file attributes, the time and date of a file, and hidden files. SortText 
sorts text data from a disk file and creates a new disk file from the result of the 
sort. The program is handy for many word-processing applications. 

SimulEgn solves systems of simultancous linear equations, 


Mortgage calculates loan repayment schedules that include balloon payments and 
monthly payment overrides. 

DoChiS9 generates chi-square tables for validation of experiments, For any number 
of degrees of freedom, you can specify cither chi-square or the probability, 
Finally, two programs create graphs of your data quickly and conveniently on the 
screen. X¥Graph plots functional curves, and BarChart draws bar charts and his- 
tograms. Complete axis annotation is included with both programs. 


Documenting the Programs 


‘The documentation of each full program in this chapter differs somewhat from that 
‘of the individual subprograms. Each explanation begins with a statement of the 
Purpose and consists of the following sections. 


Usage 
‘This section provides an explanation of when and how to use the program. Included 
is a step-by-step description of input required and output produced. 

Sample Output 


A sample case is presented to illustrate the program in action. Figures are included 
to depict the representative session. 
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Program Listing 
‘This section contains a complete listing of the Turbo Pascal source code for the 
program, printed on a shaded background for easy reference. When you save one 
‘of these full programs on disk, use the extension . PGM (for example, Sor tText. PGM) 
‘or choose some other extension that differentiates a full program from a subpro- 
‘gram. (See Appendix A.) 


Variables 
Each variable in the program is listed with an explanation of 





Discussion 


This section contains information to help you make effective use of the program, 
‘The discussion may include cross-references to the included subprograms; appli- 
cations of the program that may not be obvious; theoretical foundations; details of 
the programming techniques involved; and information about speed, memory use, 
‘or other resource requirements. 


Modifications 


In this section are offered specific changes you can make in the source code so 
that the program will work slightly differently. Thus, you can tailor the program 
to your exact needs. 


NewsWire 
Purpose: To display moving messages on the screen 











Usage 

NewsWire turns your computer into a moving “ticker tape” message center. With 
this program, you can enter any message up to 8,000 characters long and then have 
it repeatedly scroll from right to left inside a framed message box. This technique 
creates an attention-getting display for announcements, advertising promotion, or 
just plain fun. 

‘To use NewsUire, you must first type the message you want displayed. The program 
stores the message in a string array. Each array clement can be up to 80 characters 
long; a maximum of 100 elements is allowed in the array. Thus, your message can 
contain up to 8,000 characters. If this is insufficient, see the Modifications section. 
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‘The program prompts you for the text to place in each clement of the array. For 
the purposes of NeusUire, these elements are concatenated into one long message. 
‘Therefore, you place a blank space (if appropriate) at the end of each entry line 
‘so that the message is readable after concatenation. As the message is displayed, 
it is continually repeated. Because of this, you may want to put several blank spaces 
at the end of the message. When you are finished entering the entire message, type 
END (all uppercase) to signal the end of data entry. For an illustration of this entry 
Process, here is how you might enter one of Woody Atlen’s pearls! 





“More than any other time in history, mankind faces a 
crossroads. One path leads to despair and utter 
hopelessness. The other, to total extinction. Let 
us pray we have the wisdom to choose correctly.” 

— Woody Allen. . . . 
END 


onsane 


‘One blank space is included at the end of each of the first four lines, and several 
blank spaces appear at both the beginning and end of line 5. 


If you try to make an input line longer than 80 characters, that line is truncated 
to 80 characters. Data entry terminates automatically if you input 100 lines. 


‘Once the data entry is complete, the program prompts you to press a key to begin 
the display. Your message scrolls from right to left inside a framed display box. 
‘The message repeats until you press a key to terminate the program, 


Sample Output 


It’s hard to show a moving video display in a static book, but we can give you some 
of the flavor of NewsUire. Figure 18.1 shows the data entry for a short, promotional 
message from a couple of objective authors. Figure 18,2 is a “snapshot” look at 
(part of) the moving message in progress. 


From Woody Allen, Side Effects (New York: Ballantine Books, 1981), 
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NewsWire - Create moving messages. 





48 Enter text data. Array size = 100 lines #8 
44 Enter END to end data entry. #8 
1: Look for more books by Rugg & Feldman! ! 
2: from Que -- the leading microcomputer book 
St publisher... --- 
4: END 
¥8 Data entry complete 














Press a key to start the news wiri 
Once it begins, you can press any key to atop it. 





#8 PRESS ANY KEY TO CONTINUE #4 


Fig. 18.1. The data entry for Newstire is complete. 








Fig. 18.2, A snapsbor look at the moving message. 


Program Listing of NewsWire.PGM 
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Variables 

TextSize ‘The maximum number of input lines that define your 
message. Each line can be up to 80 characters long. 

Textfrray ‘The string array that holds your message, It has TextSize 
number of elements, with cach clement containing up to 
80 characters. 

wk Loop indices 

LineCount ‘The number of lines of text entered into TextArray 

Leftx The leftmost X (horizontal) position (in text-character 
units) of the scrolling window 

Right ‘The rightmost X (horizontal) position (in text-character 
units) of the scrolling window 

Y ‘The ¥ (vertical) position (in text-character units) of the 
scrolling window 

DelayTine ‘The wait time, in milliseconds, between each (one 


character) scroll of the message. DelayTime defines the 
speed of the scrolling. 
Reply, Reply2 Keyboard characters detected by KeyHit 


Discussion 


If you have a business with customer foot traffic, consider using NewsWire to attract 
attention. You can use the program in a display window or inside the store to 
announce sale prices and upcoming events, or just to wax poetic. People arc always 
attracted to movement. 


Modifications 


1. TextStze is the maximum number of clements allowed in TextArray. 
‘The number is currently set to 100. If you need more space for your 
message, make TextSize a larger integer by changing the line denoted 
by (Hod. #19. 

2. The size and location of the scrolling window (and box frame) are 
controlled by the variables LeftX, RightX, and Y in the three lines 
denoted by (Hod. #2). Make the window smatler by bringing the values 
of LeftX and RightX closer together. Move the window up or down by 
changing the value of ¥. 
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3. The speed of the scrolling is set by DelayTine. Raise its value to slow 
the scrolling speed, or lower its value to increase the speed. 
4, You can try other text modes by changing the line denoted by 
(Mod. #4). Try textmode(c48) to use color. Add a texteolor and/or 
‘textbackground statement to sct any color(s) you choose. In addition, 
you can try textmode(bu@@) with (Hod. #2) in order to create a larger 
in terms of number of characters) scrolling window. And you can place 
constant message or title on your screen to accompany the moving 
message. For example, you might add the following code right after the 
textcolor statement: 
gotony(1@, 3); 
uriteln(’ HY MESSAGE FOR THE DAY"); 


TryCurvs 


Purpose: To calculate four nonlinear curve fits of XY data 








Usage 

TryCurvs analyzes X-Y data to see whether the curve fit of a nonlinear function 
fits the data better than the best linear fit. The program begins by prompting you 
for the data entry. Each “row number” is a pair of points, one for X and one for 
the corresponding Y. The X point is Entry CR, 12, and the Y point is Entry CR, 23, 
in which R is the row number. Type END (all uppercase) to indicate that the data 
entry is complete. You must enter at least two data pairs, and all values must be 
positive. 

Next, you can save the data to a disk file, Before saving, however, you are asked 
if you would like to see the directories on either disk drive (assuming that you 
have a system with two floppy disks). A menu displays the various options. If you 
do elect to save the data, you must type the filespee you want. If you don't include 
a drive specification, the default drive is used. 


Last, the curve fits are displayed. Four nonlinear forms are compared to the linear 
(straight line) curve fit. A correlation value for each curve fit enables you to see 
which one works best 





Sample Output 


Suppose that a technician runs a series of lab experiments. Each one results in 
rapidly rising X-Y data. She uses TryCurvs to find the best functional fit because 
she wants to approximate the data with a mathentatical formula. Previously, she 
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has run three experiments and saved the data in a file named EXPTn.DTA, in which 
fn is one of the three experiment numbers. Figures 18.3 through 18.5 show how 
she applies TryCurvs to her fourth experiment. 


TryCurvs ~ Fit nonlinear functions te X-¥ deta 


Type END (all caps) when all data :© input. 
The data mist now be input. 
=-Row number 1 
Entry C1,13: 1.5 
Entry £1,233 9.26 
Row number 2-~ 
Entry €2,13: 1.9 
Entry (2,2): 0.45 
=-Row number 3 
Entry 3,13: 2.3 
Entry (3,23: 0.81 
--Flow number 4—— 
Entry 4,13: 2.8 
Entry (4,23: 1.51 
Flow number S~~ 
Entry (5,13: 3.6 
Entry (5,23: 3.92 
—-Row number 6—~ 
Entry €6,13: 4.1 
Entry (6.2: 8.03 
~-Row number 7-~ 
Entry (7,13: END 


Fig. 18.3. The cata entry bs complete 











--Fow number 6-~ 
Entry (6,12: 4.1 
Entry (6,23: 6.05 

Row number 7-— 
Entry (7,13: END 

4) © rows entered. 

18 Data entry complete ## 








You can save the data on disk. Choose an option. 
1 - 1 don’t want to save the date on disk. 

2 - Show me the directory (Ar#.#) first 

3 - Show me the directory (B:t.#) Firat. 

4 — I do want to save the data on disk but don"t 


need to see a directory. 


Enter reply from 1 to 4. 





4% Directory listing for 
EXPT1.DTA EXPT2. DTA ExPTS.DTA 
48 End of directory listing, 

Enter filespee for output file, or 4% 
44 press Enter} key to cancel. 
expta.dta 








Fig. 18.4. file name is chosen for the data stomuge: 
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expta.dta 
TH 6 sets of 2 elementis) written to file expta.dta #9 
Linear Year Correlation = 0,9082870 
a = 4. 42975905616+00 





b= 2.5978096385E+00 


Logarithmic Y= a (x #8 bd Correlation = 09412909 
a = B,3674583959E-02 
b= S.00253915460E+00 


Semilog Y= (a) exptb 2 Correlation = 0.9973810 
a = 4, 7426052954E-02 
b= 1,2372845514E+00 


Hyperbolic = «Y= X / (a +X) Correlation 
a= 7.33327417B7E+00 
b = -1.79B1330154E +00. 


negative 





Reciprocal Yels tore 
a= 8.71991 16637E+00 
b = -1,24B4149572E+00 





Fig, 18.5, The curve fits are calculated and displayed 


‘As you can see, the semilog fit is best because it has the highest correlation number. 
‘The semilog fit is a substantial improvement over the simple linear fit. 


Program Listing of TryCurvs.PGM 
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Variables 


DataArray ‘Two-dimensional array of the input data. The first 
subscript references the data-pair number. The second 
subscript references an X value when the subscript is 1, or 
a Y value when it is 2 


ConvertedArray Array with the same specifications as Datafray. Here 
cither the X data or the Y data (or both) has been 
‘transformed, depending on the functional form being fit. 


Herray ‘One-dimensional array of the X values 
Yarray One-dimensional array of the Y values 
YfromX ‘One-dimensional array of Y values calculated from X 


values, using one of the functional fits 
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NunBataPairs Number of data pairs input 


Code Parameter from Save2Arr, indicating whether a file save 
‘was successful 
J Looping index 
AB Solutions to the various curve fits 
Variance Variance of the errors in each data point 
Temp ‘Temporary variable 
YStanDev Standard deviation of the input Y values 
Mink Minimum X value input (must be greater than 0) 
Miny Minimum Y value input (must be greater than 0) 
Unused Placeholder for an unneeded procedure parameter 
Reply Continuation option selected from a menu 
Discussion 


TryCurvs compares four different nonlinear curve fits to the best linear fit, The 
four nonlinear curve types are logarithmic, semilog, hyperbolic, and reciprocal. All 
these types have two parameters (A and B) and thus require at least two points 
in order to produce a curve fit. If your data has an exponential type rise or an 
asymptotic decay, one of these four curve fits will probably be a substantial im- 
provement over the linear fit. 


‘The program uses a least-squares technique to fit the data. A functional transfor: 
mation (logarithmic, exponential, inverse, etc.) is made to the X data or the ¥ dat 
(or both) as appropriate. (Look for the Conver tedArray assignments in the code.) 
‘Then LinReg is called for the functional fits. A reverse transformation provides A 
and B, the two output constants for each fit 





For each fit, the embedded function ShowResults computes the correlation, This 
provides a quantitative measure of the quality of the fit, ShowResults compares the 
differences between the actual Y values and the Y values that the particular curve 
fit produces for the corresponding X values. A perfect fit has a correlation of 1 
‘The smaller the correlation, the worse the fit A negative value means that the 
correlation is poor although the values of A and B are still displayed for these cases. 
It is not unusual to get negative correlations for the hyperbolic and reciprocal fits 
if the Y data increases with increasing X data 





For simplicity, because of possible division by zero, all input data must be positive. 
‘This applies to both X data and Y data. In addition, at least two data pairs must 
be provided. 
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Modification 


‘The maximum allowable number of data pairs is currently set to 250 in the constant 
MaxNunPairs, Raise this number if you have more data. 


PolyFit 
Purpose: To calculate polynomial curve fits of XY data 











Usage 
‘The degree of the polynomial curve fit is under your control. PolyFit can be used 
a5 a powerful forecasting tool. (See the Discussion section.) 


‘The input data (X-Y values) is read from a disk file you must have available. You 
‘can create this file with the TryCurvs program, PolyFit requires that all values of 
X be positive. If some are not, the results are meaningless. 


‘The program begins by requesting the filespec of your data file. After the file is 
ead, you select the degree of the polynomial that is used to fit your data, This 
degree is an integer from 0 to 1 less than the number of data pairs you have. PolyFit 
Prompts you by showing the allowable range. At this point, you can type Q (up: 
percase) to quit the program. 

‘The polynomial coefficients are now calculated and displayed. In addition, the cor- 
relation coefficient is given, which provides a quantitative measure of the accuracy 
of the fit 


Now you can request that values of Y be calculated for any positive X, using the 
functional fit just found. This step allows interpolation and extrapolation of your 
data. To leave this mode, simply type E (uppercase) instead of an X value. Finally, 
you can request a different degree fit to your data 


Sample Output 
For TryCurvs, you considered a technician who ran lab experiments. She created 
a disk file of X-Y data named EXPT4.DTA. TryCurus found that the best nonlinear 
curve fit for her data was a semilog fit. This fit had a correlation of 0.99738+ 
compared to the linear fit with 1 correlation of 0.90426+, 


‘The technician now uses PolyFit to find a better polynomial fit. In addition, she 
wants to calculate what values Y would have for X values of 3.0 and 4.5, Figures 
186 and 187 show the results. 
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PolyFit - Polynomial curve fitter 


The input data must now be read from a disk file. 
44 Enter filespec of input file, or 

#8 press (Enter key to cancel. ” 
EXPT4.DTA 

44 6 sets of 2 element(s) now in array. $4 





Degree to fit (0-5) or O to Quit the progra 


Entry? 2 

x Power Coefficient 
° 4.8037107970E+00 
1 ~5.1249181340€+00 
2 1,4140337212E+00 


Correlation = %.88462763806-01 


X value to evaluate or E to End evaluations 
Entry? € 


to fit (0-5) or O to Quit the program 





Fig, 18.6, A second degree fit is calculated. 





Entry? 3 
x Power Coefficient 
° -5.5114531475E+00 
4 18.6479143756E+00 
2 =a, 1832187075E+00 


71011 7687070E-01 


Correlation = 9.986079484BE-01 


X value to evaluate or E to End evaluations 
Entry? 3.0 
y= '1.7150971208€+00 


X value to evaluate or to End evaluations 
Entry? 4.5 
Y= | 1.25887250S8+01 





X value to evaluate or E to End evaluations 
Entry? E 


Degree to fit (0-5) or D to Quit the program 
Entry? 


Fig. 18:7. A thin degree fit is calculated and evaluated 


‘The third degree fit has a correlation of 0.99860+, and that fit is therefore the 
lowest degree polynomial that improves on the semilog fit found by TryCurus, 


Program Listing of PolyFit.PGM 
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Variables 

DataArray ‘Two-dimensional array of the input data. The first 
subscript references the datapair number. The second 
subscript references an X value when the subscript is 1, or 
a Y value when it is 2, 

Array Array of the X data from Datafrray 

Yarray Array of the ¥ data from DataArray 

PowerArray Array of various powers of X 

RHS Array of the right-hand sides of the equations 

Coeffs Array of the solutions to the equations. These solutions are 
the coefficients of the various X powers. 

Factors ‘Two-dimensional array of the factors needed to solve the 
equations for Coeff's 


NunDataPairs Number of data pairs 
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Degree Degree of the polynomial to be fitted 

TwoDegree ‘Twice Degres 

NunEgns Number of equations to solve (Degree + 1) 

Code Parameter from Load2Arr, indicating whether a file was 
read successfully 

KLM Looping variables and array subscripts 

Last Highest degree that can be fit 

CharFlag Character read in from keyboard 

TineToQuit boolean flag set to true when program is finished 

Noor eToDo boolean flag set to true when no more X values are to be 


evaluated for the current polynomial 

Dummy variable and placeholder in call to Stats 
Numerator used in calculation of correlation 
Denominator used in calculation of correlation 
Coefficient indicating the goodness of fit 

Mean value of the Y data 





Value of X for which to evaluate the current polynomial 
Value of ¥ for a given X 


Discussion 


Both TryCurvs and PolyFit provide analytic functions to fit a set of X-¥ data, In 
TryCurvs, various nonlinear functions are tried; here polynomials of arbitrary degree 
are computed. PolyFit fits a curve of the following form to your data: 





Y=Cy +C,X! + GX? +... + Cy x” 


‘The maximum value allowed for D is seven (or one less than NuaDataPairs if you 
have fewer than cight data pairs). The values of C are the constant coefficients 
calculated by PolyFit. A correlation value is also displayed. This correlation is 
analogous to the correlations calculated by TryCurvs. Thus, the correlations trom 
the two programs can be directly compared for the goodness of fit 

‘There are many reasons why you might want an analytic function to represent your 
XY data. Such a function can smooth out the fluctuations in Y found in most physical 
experiments. Using an analytic function also is a convenient way to represent your 
data in a computer program. Most important, an analytic function provides a way 
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to compute functional values of ¥ for values of X not explicitly in your data. These 
can be values of X between known points (interpolation), or values outside known 
points (extrapolation). If used cautiously, such a function can become a forecasting 
tool. By extrapolating your known data, you can make predictions of future results. 


‘The least-squares technique is used for the curve fitting, This technique minimizes 
the sum of the squares of the errors at each data point. Because the Power function 
does not allow negative bases, all values of X in PolyFit should be positive. This 
applies to your input data and to values of X you want evaluated after the fit is 
found, Negative X values result in meaningless answers. 


TryCurvs and PolyFit work nicely together. Your data file can be created with 
TryCurys and later used by PolyFit, Be careful if your file contains duplicate data 
pairs. The degree of fit must be at least one less than the number of unique data 
pairs, Otherwise, division by zero is possible 


Modifications 
1, The maximum allowable number of data pairs is controlled by the 
constant RouSize, which is currently set to 250. Raise the number if you 
have more data in your data file 


2. The constant MaxDegree determines the langest degree fit that PolyFit 
allows you to choose. You can make the degree larger than the current 
value of 7 if you want. However, unless your data is well behaved (X 
and Y values are near 1), computational accuracy degrades quickly for 
fits higher than the seventh degree. PolyFit is dimensioned adequately 
to accept MaxDegree up to 14, but a practical limit for MaxDegree is 7, 


SortDir 


Purpose: To display a sorted listing of a disk directory 











Usage 


‘This program displays in alphabetical order the file names in a root directory or 
subdirectory. When prompted, you simply provide the disk drive and path you want. 
‘The output format of SortDir is similar to the output format of the DOS DIR 
command, but this program displays a bit more. In addition to the file name, si 
and date and time of the last update, SortDir displays the file attributes and the 
day of the week of the last update. In addition, the time of the last update is shown 
to the second, not just to the minute. Unlike DIR, this program shows hidden files 
also. 
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Sample Output 
Figure 18.8 shows the output produced by Sor tDir if a test disk is in drive B. Note 
that all the files, except the subdirectory, have the archive attribute set (A at the 
far right). Note also that the two DOS files with names starting with IBM (these 
files are from DOS V2.0, by the way) are marked as hidden, read-only, and system 


files. 

Enter drive and path for sorted directory listing 

Br 

8 files found. Sorted listing: 

CHKDSK. COM 6400 BE- 3-8 Tue 12: 0:0 A 
COMMAND.COM 17664 G3- 5- 8 Tue 12: 0: 0 A 
DAYWEER. PSL 667 @6- 2-11 Tue 14:19:52 A 
FILEINFO. PSL 1603 @6- 2-2 Sun 19:57:42 A 
TBMBIO. COM 4608 83-35-68 Tue 12: 0: 0 A HRS 
IBMDOS. COM 17152 83- 3- 8 Tue 121 Or 0 A HRS 
SORTDIR.PGH 1968 G6- 2-14 Fri 4:25:12 
EDIMONTHLY. DAT 0 B6- 2-15 Sat 18:12:32 D 


Fig. 18.8. 4 sample session with SortDir. 


Program Listing of SortDir.PGM 
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Variables 

FileSpee ‘The file specification, used for retrieving the file names at 
the beginning of the program, and the Filelnfo data at 
the end 

Path ‘The drive and path entered from the keyboard 

Name ‘The file name found by NextFile 

AttrList ‘The list of attributes found by Filelnfo 

DayName ‘The weekday name found by Daylieek 

Textfrray Array of file names, sorted by SorthT 

FileBytes ‘The size of a file in bytes 

Code Condition code returned from NextFi le 

Ay Subscript of file names as found; counter of number of 
files found 

K ‘Subscript of sorted file names as displayed 


Year ‘Year of a file's last update (integer form) 


538 ‘TURBO PASCAL PROGRAM LIBRARY, 





Attr Attribute byte NextFile uses when searching the directory 

Yr ‘Year of a file's last update (byte form) 

Mon Month of a file's last update 

Day Day of a file’s last update 

Hr ‘Hour of a file’s last update 

Min Minute of a file’s last update 

Sec Second of a file’s last update 

DayNum Day number of the weekday that a file was last updated 
Discussion 


This program uses NextF ile to retrieve all the file names in the specified directory, 
then SortHT to sort the names into alphabetical order, and finally FileInfo and 
Dayeek to retrieve information about each file name. SortDir does not pause after 
the screen fills with file names, although you could easily modify the program for 
pausing. Instead, you can simply press Ctrl-S to make the displaying pause and then 
continue. 


Modification 


To allow for more file names, change 268 in the line indicated by (Hod. 1. For 
the root directory of a floppy disk, 200 is plenty. For subdirectories (especially for 
fixed disks), you may need to allow for more file names. 


SortText 
Purpose: To sort text data from a disk file, creating a new disk file 











Usage 
Many word-processing programs have no sorting capability, yet you may occasionally 
need to alphabetize text data. This program enables you to sort a text file. The 
sort key can be located anywhere within the text line, as long as the key is in the 
same location (column) in each line. For example, suppose that you have a list of 
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names and addresses for which cach entry (name and address combination) oc- 
cupies one fine. The last name starts in the first position of each line and occupies 
the first 14 characters. Following the last name is the first name, which is no more 
than 12 characters. In this case, the sort key you want begins in position 1 and is 
26 characters long. 


SortText asks you for the location and length of the sort key (that is, the portion 
of each text line which is the basis for alphabetizing the data). The program then 
displays the disk directory that is currently active and asks you to enter a filespec 
(disk drive, path, and filename; only filename is required ) to indicate the file you 
want sorted. The program reads the input file into memory, sorts the file, and asks 
you fora filespec for the output file. After writing the output file to disk, the program 
displays a message showing that the file is successfully saved, Then the program 
ends. 


Sample Output 
Figures 18.9 and 18,10 show a typical run of SortText in which a small test file 
is sorted. 


S488 SortText Program #sae 





Maximum text lines that can be sor 
Maximum length of each teat line = 





For the sort key: 


Enter the position number it starte in. 
Entry? 1 


Enter the sort key length. 
Entry? 26 


F in current active directory are 
48 Directory listing for #-# 

COMPIAND.. COM INDEX. DAT SORTTEXT.-PGM 
M8 End of directory listing. #8 





#8 Enter filespec of input tezt file, or ## 
49 press (Enter) key to cancel. ” 





Fig. 18.9. The filespec must now be input 
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Enter the sort key length. 
Entry? 26 


Files in current active directory are 
48 Directory listing for 8.8 
COMMAND.COM INDEX. DAT SORTTEXT.PGH 
#8 End of directory listing. 








44 Enter filespec of input text fil 
*% press [Enter] key to cancel. 
INDEX. DAT 

#45 lines now in text array. #6 





5 lines of text sorted 


’ 
We pr 
INDEX. SRT 

S text Lines written to file INDEX.SRT 





Enter filespec for text output #11 
[Enter] key to cancel. 





Sorted file succemsfully saved 


Fig. 18.10, SortText croutes the sorted text fle. 


Program Listing of SortText.PGM 
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Variables 
Textfrray 


LineCount 
Code 
Position 
uidth 
CharEntry 


FileSpec 


Discussion 


string array that holds the data read from the input file 
and in which the data is sorted 


Number of text lines read from the input file 
Error code used by several subprograms 
Starting position of the sort key 

Size of the sort key 


Possible single-character entry returned from GetNunl 
subprogram. CharEntry is not used, 


‘The file specification ShouDir uses to display the directory 


contents 


‘The logic of SortText is straightforward. The program's “backbone” consists of 
LoadTxt, which loads the file into an array; SortHT, which sorts the array; and 
SaveTxt, which saves the sorted array back to disk. Other parts of the program 
exist only for communicating through the screen to obtain necessary information 
(the sort-key specifications) and to display status messages (number of lines sorted, 
error messages, etc:). 


Modifications 


1, Change the two numbers in the lines indicated by (Mod, #1) to fit the 
text data you are working with. TextSize is the maximum number of 
text lines, and LineLength is the maximum length of each line. Because 
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‘Turbo limits the size of your data area to no more than 64K, you cannot 
make these numbers excessively large. As shown here, the text array 
takes up 500 times 81, or 40,500 bytes. 


2, As written, this program displays the active directory before asking for 
an input file name. You can change this directory by altering the two 
indicated lines. For example, to display the root directory of disk drive 
B, change the first line to 


FileSpec :=’ Bs. 0’; 


Another possibility is to replace both indicated lines with a brief 
dialogue, asking at run-time which directory should be displayed. 


SimulEqn 


Purpose: To solve a set of simultaneous linear equations 














Usage 
‘The need to solve simultaneous equations arises regularly in scientific and numerical 
work. Algebra students encounter such equations regularly, Many “word” problems 
can be solved by constructing the correct set of simultaneous equations. 


‘The program is set to solve three equations in three unknowns. You can easily 
change this number (3) by redefining the values of two constants in the const 
block. (See the Modification section.) 


First, the program prompts you for the data entry. For cach equation, you must 
provide the coefficients of each unknown and the righthand side. When you com- 
plete the data entry, a prompting message tells you to press a key to continue, The 
screen then clears, and the program reformats the data and displays it for your 
review. 


‘You now have three continuation options: (1.) proceed (the data is OK), (2) reenter 
the data (the data is entered incorrectly), and (3) abort (an error in problem 
formulation exists). If you proceed, SimulEgn calculates and displays the solution. 


Sample Output 


Consider the following set of three equations with the unknowns X, Y, and Z: 


15X- 20Y- 622 
05x +25Y 
21X+14Y- 15Z = 48 
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Figures 18.11 
X,Y, and Z, 


SIMULEON - A simultaneous Lin 
The program is currently set to do 5 equations in 


The data must now be input. 


through 18.13 show SisulEgn being used to solve this problem for 





F equation solver 


3 unknowns. 


You will be prompted 


for the coefficients and right-hand side of each 


wquation (or row 
Entry CA,BI mean; 
When B ="4, provi 


=-Fom number 1 
Entry (1,132 


Pig, 18.11, 


) one at a time. The notation 
% cowfficient B of equation A. 
ide the right-hand aid 





The data entry 65 ready t0 begin. 





When B= 4, prov) 
ow number 1-~ 
Entry (1,132 
Entry (1,23 
Entry (1,332 
Entry (1,433 
Row number 
Entry (2,12 
Entry (2,23: 
Entry (2,33: 
Entry (2,432 
Row number 3: 
Last row 64 
Entry (3,13: 
Entry (5,235 
Entry (3,332 
Entry (3,432 
3 rows enteres 















You naw have oe 


44 PRESS any KEY 


Fig, 18.12. 


ide the right-hand side. 


1s 





6.2 


3.7 


2.4 





2.4 
ia 
-1.5 

4.8 


arr 


Data entry complete #8 


hance to review the data. 


TO CONTINUE 44 


‘The data entry is complete 
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(1,12 125000 1,23 -2.0000 £1,321 -6.2000 
£211] 0.5009 2,22 2.5000 2131 0.0000 
[3,11 2.1000 £3,232 1.4000 3,33 - 
#8) Press 2 key to continue #6 


41 3.7000 
‘41 -2.4000 
£3143 428000 








‘This is the data you entered. Is it correct? 


1 - Yes it is} please continue. 
2 No it's not; let me reenter it. 
3 — No it’s not: please abort the program. 





Enter reply from 1 to 3. 
4 


The solution is. 
Unknown 1 = 4,2000000000E +00 
Unknown 2 = -1.8000000000E +00 
Unknown J = 1,0000000000E+00 


Pig, 18.13. The solution is calculated and displayed 


‘Thus, the answer to the sample problem is the following: 





X = 42 
Y =18 





z= 10 


Program Listing of SimulEqn.PGM 
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Variables 

Egnfrray Array of the input data. The array is two-dimensional of 
size [NumEgn, NunEgn + 1], in which NunEgn is the number 
‘of equations. The first subscript references the equation 
number; the second subscript references the unknown. 
When the second subscript equals NumEgn + 1, the 
reference is to the right-hand side of the current equation. 

EgnCount ‘The number of equations for which data was entered 

Jk Loop indices 

OK boolean flag indicating whether the solution is possible. If 
OK is true, a solution was found. If OK is false, no solution 
is possible 

Reply Keystroke made in response to a program prompt 


Coeffttatrix Array containing the input coefficients for each equation 
and each unknown 


RHSHatr 1x Array containing the values for the righthand side of each 
‘equation 


Invertedtiatrix ‘The inverse array of Coef ftiatr ix 
Answertatrix Array containing the solution for each unknown 


Discussion 


Because Turbo does not allow you to pass variable-sized arrays to procedures and 
functions, the size of the arrays (that is, the number of equations being solved) 
must be “hardwired” into the program as a global declaration. The constant NunEgn 
is thus set to the number of equations to be solved. For compatibility with the 
included subprograms Key2Arr (Chapter 2) and Show2Arr (Chapter 4), a second 
constant, NunEgrP lust, is set also. It has a value of Nuségn + 1. These two constants 
are defined at the beginning of the const block. Make sure that they are set ap- 
propriately for your particular case. 


Data input is under the control of Key2Arr. This subprogram prompts you for data 
for a two-dimensional array. Key2Arr displays Row number on the screen, prompting 
in the general case) for array input one row at a time. For the purposes of SimulEgn, 
row is simply an equation, and the terms row number and equation number are 
synonymous. 


If your data is ill-conditioned, the program cannot calculate a solution. When this 
happens, the program beeps, and a message is displayed to indicate this error con- 
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dition, The two most likely causes of this error are that all the coefficients of one 
‘equation are zero, of that one equation is an exact multiple of another. 


SimulEgn solves the matrix equation (A)(X)=(B). Here, A is the square coefficient 
matrix. X is the column matrix of the unknowns, and B is the column matrix of 
the right-hand sides. The solution is given by (X)=(A inverse )(B). Thus, the solution 
technique is to invert Coeffttatrix and multiply it by RHSMatr ix, 


Hattult, which is the subprogram that does the multiplication, operates only on 
‘square matrices. Therefore, the matrix RHSMatr x is expanded from its natural col- 
umn form into a full square matrix and filled with zeros in the extraneous ele- 
ments. The resultant matrix, from its multiplication with (the naturally square) 
Coefftatr ix, is AnswerMatrix. It contains the solution for all the unknowns in its 
first column, 


Modification 


Reset Nunéign and NusEgnPlust when the number of equations to be solved changes, 
Set NunEgn to the number of equations (and thus the number of unknowns also), 
‘Set NunEgnPlusi to one more than NunEgn, 


Mortgage 





Purpose: To calculate and display loan repayment schedules 








Usage 

‘This program can help take the frustration and mystery out of many loan de 
When you are faced with financing a house, a car, or any major purchase, many 
questions arise. How is your monthly payment affected by the size of your down 
payment? How does a 25-year loan compare with a 30-year loan? How much of 
your payments this year go toward tax-deductible interest? How large is your “bal- 
loon” payment if you take that second mortgage? This program shows you the 
answers 





First, the program prompts you for the fundamental loan specifications. These are 
the principal, annual interest rate (as a percentage), and length of the loan in 
months. 


A conventional mortgage is assumed. This means that a payment is made every 
month, all payments (except perhaps the last) are equal, and interest is com: 
pounded with cach payment. Some of these assumptions can be adjusted, See the 
Modifications section. 
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After you supply the input, the regular monthly payment is shown. You now have 
the option of overriding this payment and, instead, specifying a different monthly 
payment. Using this option results in a balloon payment (if you reduce the normal 
payment) or an early amortization of the loan (if you increase the normal payment). 
See the Discussion section. 


Next, an analysis of each year of the loan is presented. For cach month, you are 
shown the current loan balance, the contribution paid toward interest, and the 
contribution paid toward principal. The cumulative totals are shown also. 


After «year’s worth of information is displayed, you can cither see the next year 
of information or go immediately to the final totals. A prompt asks you to press 
the Enter key for the next year of information, or the T (or t) key to sce the totals, 


‘The final totals include the amount of the last payment, the sum total ofall payments, 
the total number of payments, and the ratio of the total of the payments made to 
the principal of the loan. 


Sample Output 


Suppose that you need a short-term second mortgage for $5,000. Your bank offers 
an 18:month loan at 14.5 percent interest. You initially can afford to pay only $250 
a month in repayment, Because the normal payment is over $300 a month, the bank 


agrees to a balloon payment at the end. Figures 18.14 through 18.16 show the 
analysis of this loan, 





Mortgage - Analysis of # loan repayment 


Please enter the principal. 
Entry? 5000 





Fleane enter the annual interest rate. 
Entry? 14.5 


Pleae enter the length of the loan in months. 
Entry? 18 


Regular payment i= 310.75 
De you want to override this (¥ or N)> Y 


Please enter the desired payment. 
Entry? 250 


Fig. 18.14. The loan data ts entered 
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Mortgage — Analysis of = loan repayment 


Principal - 
Interest rate = 
Regular payment = 
Term in months = 


Remaining 

Paymt. Balance This time 
1 4810.42 169.56 
2 $616.55 191.87 
S  4aza.se 194.19) 
4 4227.82 196.58 
S 4028.91 198.91 
6 = 3827.59 201.32 
7 3623.84 203.75 
8 3417.65 206.21 
9 3208.93 208.70 
10 2997.70 211.23 
11 2783.92 213.78 
12 2567.56 216.36 








T for Totals or (Enter) for next screen. 


Fig. 18.15. The first ywar of the loan & analyzed 


~Amount Amortized~ 


To date 
189.58 
381.45 
375.63 
772.18 
971,09 

A173.) 

1376.16 

1562.57 

1793.07 

2002.30 

2216.08 

2as2. 08 





Mortgage ~ Analysis of a loan repayment 














Prine = 5000.00 

Inter - 14.50 

Regular payment = 250.00 

Term in months = 18 

Remaining =--Interest Paid~ “Amount Amortiz) 

Paymt. Balance Thia time To date ‘This time To date 
13 2348.58. 31.02 218.98 2651.42 
18 2128.96. 28.38 221162 2873.04 
15 1902.66 25.70 224 3097.54 
16 1675.65 22199 227.01 3324.35 
17 1445.90 20.25 229.75 3554.10 
18 0.00 17187 1445.90 5000.00 

Last payment = 1463.37 

Total payments = 5713.37 

Total number of payments = 18 


Ratio of total payments to principal = 1.1427 


Fig. 18.16, The last six months are analyzed, and the final totals are shown. 


Program Listing of Mortgage.PGM 
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Variables 
Principal Principal of the loan. 
Payment ‘Current monthly payment 


FirstPayment Payment for the first month 
InterastRate Annual interest rate as a percentage 


Interest Interest paid in the current month 
Balance Current loan balance 
IntFactor Monthly interest rate 
Amortized ‘Amount paid to principal in the current month 


TotalPaynents Cumulative sum of the payments to date 
Totalinterest Total paid to interest to date 
TotalAnort ‘Total paid to principal to date 
TotalNusPay Total number of payments to be made 
Code Return flag from GetNu® or GetNunl 
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LineCount. Number of months of information displayed to date 
PayNum Payment number 

LinesToShow Number of months of information to display on one screen 
CharFlag Character returned by GetNuaR or GetNunl 


Reply, Reply2 Characters returned by GetKey 
UantToSeelt boolean flag indicating whether more output is wanted 


Discussion 


Unfortunately, many tending institutions differ in how they compute amortiza- 
tion tables, especially in calculating the monthly payment. Many institutions round 
the true value up, often to the next whole dollar, and sometimes even more, In 
Mortgage, all dollar figures are rounded (up or down) to the nearest cent, 


‘The interest rate you provide should be the annual percentage interest, such as 
12.0 or 8.75, Mortgage assumes that repayment is monthly, that all payments are 
equal (except the last), and that interest is compounded with each monthly 
payment 

Don't overlook the flexibility allowed by the option of overriding the standard 
monthly payment. This option accommodates the common practice of second mort- 
‘age loans to allow smaller monthly payments with a large balloon payment at the 
end. You can try various monthly payments to see how they affect that last big 
payment. And you can try making larger than normal payments to see how fast the 
principal is paid off, 

‘The following restrictions apply to your input. Principal must be positive real 
number, InterestRate must be a real number greater than 0 (zero) and less than 
100, Tota NunPay must be a positive integer less than 2000. Payment (if you override 
it) must be a positive real number. Principal and Payment are rounded to the 
nearest penny, if necessary. 

Mortgage includes the subprograms GetKey, GetNual, and GetNuaR (all in Chapter 
2) for data input; Tab (Chapter 4) for output formatting, and LoanPay (Chapter 
14) for calculating the standard loan payment. 





Modifications 


1. The string constant TeraString identifies the time period between 
payments. The constant is set to months (TerString = ‘months’ ), 
which is appropriate for most loans. Thus, the word months is displayed 
in the annotations. However, you can change TernString to something 
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clse for consistency with the next modification. Change TeraString by 
altering the constant in the line denoted by (Hod. #1) 


2. The constant NusPayPer'r identifies the number of payments to be made 
per year. This number is set to 12 for the usual monthly repayment. You 
may want to set the constant to 1 (annual payments), 4 (quarterly 
payments), or something else. Adjust NusPayPerYr in the line denoted by 
(Mod. #2), 

3. The number of payment lines to display on one screen is set in the 
variable LinesToShou. The number is nominally 12 to show one year's 
worth of data at a time. Make the variable bigger or smaller by changing 
its value in the line denoted by (Mod. #3). 


DoChiSq 
Purpose: To generate chi-square tables 











Usage 
‘This program provides the seldom-found capability of calculating your own tables 
‘of the chi-square distribution, Most references simply provide a (frequently sparse) 
table. Sometimes you need more accuracy or values not found explicitly in your 
reference. See the GetCh1S9 and ChiProb subprograms in Chapter 13 for a general 
explanation of the chi-square test and the terminology used here. 


First, the program prompts you for the number of degrees of freedom in your 
problem. This number can be any positive integer. Next, you can either specify the 
value of chi-square and have the probability calculated, or specify the probability 
and have chi-square calculated. The program asks which you prefer. Type € to 
‘specify chi-square, or P to specify the probability. You can use either uppercase 
or lowercase. 


Finally, you must give your input value for either chi-square or the probability. Chi 
square values are positive real numbers. Probabilities are real numbers between 0 
and 1. (See the Modifications section. ) The answer is then computed and displayed. 


Sample Output 


‘Two sample runs are shown in figures 18.17 and 18.18, A value of chi-square 
specified in the first, and a probability is specified in the second 
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DoChiSq - Generate chi-square tables 


Degrees of fr 
Entry? & 


dom? 





Which would you like to specify, © or F 7 
© - Chi-square 
P ~ Probability 

Which one? © 





Value for Chi-squar 
Entry? 11.4 
Probability = 








s004807437E-01 


ig. 18.17. The probability és calculated from chi-square 





DoChiSq - Generate chi-square tables 


Degrees of freedom? 
Entry? 50 


Which would you like to mpecify, © or P > 
© ~ Chi-square 
P ~ Probability 

Which ene? P 


Value for Probability? 
Entry? 0.95 
Chi-uquare = 3.4763431549E+01 


Fig. 1.18, Chispare is calculated from the probably. 


Program Listing of DoChiSq.PGM 
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Variables 
LoProb Lowest probability you are allowed to input 
HiProb Highest probability you are allowed to input 
ChiSg Value of chi-square (input or calculated ) 


Probability Probability that an experiment characterized by 
DegFreedon will result in a chi-square higher than ChiS9, 
Probability must be between 0 and 1 


Unused Placeholder for an unused parameter in the call to 
NoraDi s 

CunDis ‘The normal cumulative distribution function as returned 
by NoraDis 

LoChiSg A lower bound on chi-square (see Modifications ) 

HiChiSg ‘An upper bound on chi-square (see Modifications) 

Numer ‘The numerator in the calculation of Norm 

Term Temporary term 

Norax Abscissa value of X for the call to NormDis 

DegFreedon Degrees of freedom. DegFreedon must be a positive 
integer. 

Code Return code from GetNual or GetNuaR 

x Convergence indicator. If OK is truc, Root successfully 


converged to an answer. 
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CharFlag Character returned by GetNual or GetNumR 

Reply Character returned by GetKey 

Reply2 Character returned by GetKey 
Discussion 


The subprogram ChiProb provides the capability of calculating probabilities, given 
chi-square for degrees of freedom less than 30. DoChiS9 extends that capability t0 
larger degrees of freedom. In addition, you can do the reverse problem—finding 
chi-square given the probability. 

‘The technique for solving the problem is interesting, (We'll have to gloss over the 
mathematics because of space limitations.) The embedded function GetProb cal- 
culates the probability given DegFreedom and ChiSg. This calculation is simple when 
DegFreadom is less than 30, because the subprogram ChiProb does the calculation 
directly. For a larger DegFreadoa, the desired probability can be excellently ap- 
Proximated with a normal distribution. A transformation along the abscissa (X) of 
this distribution is required, This transformed X, called NormX, is a function of 
DegFreedom and ChiSg. (In ChiProb the variable X is chi-square and equals the value 
ChiSq has outside ChiProb.) When NoraX has been computed, the subprogram 
NoraDis is called to get the probability. 


‘The inverse problem uses Root (Chapter 12) to solve for chi-square given the 
probability. The function MyFune is simply GetProb minus the desired probability. 
Root adjusts ChiSy until MyFunc becomes zero. 


For ease of reference, the included files are grouped together near the top of the 
listing, The Root subprogram, however, needs MyFunc defined within Root's block. 
Therefore, MyFune is declared with a forward reference before the included files. 
‘The body of HyFune comes later. 








Modifications 


1, LoProb and HiProb control, respectively, the lowest and highest values 
you are allowed to use for Probability. The current ranges should be 
adequate for any practical problems, but you may adjust the ranges if 
you want. Of course, LoProb must be greater than 0, and HiProb must 
be less than 1. 


2, LoChiSg and HiChiS9 provide bounds on the range of chi-square when 
Root is called. (Root is used when you specify Probability and want to 
calculate ChiSg.) Overflow can occur if this range in chi-square is much 
wider than the chi-square values that LoProb and HiPrab would compute 
for a given DegFreedom. The lines indicated by (Hod. #2) provide 
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functional approximations for LoOhiSg and HiChiSy. You may need to 
‘change these lines if you use modification 1. If an overflow (or “can't 
converge” message) occurs, adjusting these lines appropriately should 
cure the problem. 


XYGraph 


Purpose: To draw a graph of X-¥ data on the screen 











Usage 
Nothing conveys bivariate numerical data more effectively than a well-posed graph. 
‘Trends, minima, and maxima are easily discerned. This program provides a full- 
featured graphics presentation tool. 


You have control over the size of the graph, the axis labeling, and the scaling, (See 
the Modifications section for several ways to adjust the final appearance of your 
graph.) The data to be plotted must be in a disk file containing the X and Y points 
as paired data entries. You can use the subprogram Save2frr (Chapter 6) to create 
this file. 


‘The program begins by prompting you for the filespec of the disk file containing 
the X-¥ data. The data is then read from disk into an array for use by XYGraph. The 
data pairs are sorted to ensure that the X values are in ascending order. 


Now you must provide the specifications for the graph (scaling, axis labeling, etc.) 
First, the x-axis is considered. This is the abscissa, or horizontal axis, of the graph. 
‘The program requests the X values to use at the left and right ends of the axis, 
‘To aid you in deciding, the program displays the lowest and highest values of X 
‘occurring in your input data file. Typically, you want round numbers at the axis 
extrema in order to create easily readable graphs, but any real numbers are ac- 
ceptable (as long as they aren't equal). 

Next, you provide the number of primary tick marks to use along the axis. This 
number must be an integer greater than or equal to zero. One tick mark is placed 
at each end of the axis. The remaining tick marks, if any, are equally spaced along 
the axis, If you request less than two tick marks, none is displayed. Secondary tick 
marks are provided automatically between the primary tick marks. Last, you provide 
the label for the whole axis. This label should be limited to about 60 characters. 
If you prefer, you can simply press Enter to eliminate the label completely. 


AA similar dialogue then transpires for the y-axis specifications. The y-axis is the 
ordinate, or vertical axis, of your graph. 
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When prompted, you simply press any key to produce the graph on the screen, 
‘The graph is drawn in high-resolution graphics with white lines on a black back- 
ground, Axis labeling and centering are done automatically. After viewing the graph, 
you press any key to clear the screen, return to text mode, and end the program. 


Sample Output 

XYGraph can be readily used to plot mathematical functions. This application is 
demonstrated here with a plot of the SIN function. Before this run of X¥Graph, the 
‘SaveZArr subprogram was used to create a disk file called SINDEMO.DTA. This file 
contains pairs of X-Y data points for one full period of the SIN function. X runs 
from 0 to 6.28 in steps of 0.04. Y is the corresponding value of SIN(X). In figures 
18.19 and 18.20, the graph specifications are provided. Figure 18.21 shows the 
resultant graph. (‘This figure was created on an EPSON printer by using Shift-Prisc 
with GRAPHICS.COM to get an image of the screen.) 


xYGraph ution graph of X-¥ date 





== X-Aiiw Specifications —~ 


Smallout X value in data file = 0.000000E+00 
Largest X value in data file = 6.280000E+00 





K value at the left end of the axis? 





Entry? 0.0 
X value at the right end of the axis? 
Entry? 

Number of primary tick marke on axis? 
Entry? 8 

Label for x-axis? 


2X (Radiane) 


Fig, 18.19. Reading the data file and specifying the xaxts 
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= Specifications —— 


Small 
Lara 


tt Y value in data file = -9.99971E-01 
Yi value in data file = 9.999417E-01 








¥ value at the bottom of the exis? 
Entry? -1.0 
Y value at the top of the axis 
Entry? 1.0 





Number of primary tick marks on axis? 
Entry? 5 


Label for y-axis? 
2 SIN 


Prews a key to see the graph. When finished, 
a key to clear the screen 








1,08 





1.08 


2.00 3.08 4,00 5.08 
X (Radians) 





Fig. 18.21, The graph of ¥ = SIN(X) 
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Program Listing of XYGraph.PGM 





FULL PROGRAMS CONSTRUCTED FROM SUBPROGRAMS 











PROGRAMS CONSTRUCTED FROM SUBPROGRAMS 





570 ‘TURBO PASCAL PROGRAM LIBRARY. 





Variables 
XYDatafrray ‘The two-dimensional array containing the X-Y data read 
from the input disk file 
TestArray One-dimensional array of cither the X data or the Y data 


XTextArray string array of the annotations for the x-axis, The zero 
element contains the label for the whole axis. The 
clements from 1 upward contain the labels for the primary 


tick marks, 
YTextArray string array of the annotations for the y-axis 

RowCount Number of data pairs in XYDataArray 

Code, Code2 Return codes from GetNual and GetNuaR 

J Loop index 

NunTicks Number of tick marks to put on an axis 

01dx, Oley last value of X and Y in graphing coordinates 

New, Now Current value of X and ¥ in graphing coordinates 
XOrigin X location of the origin in graphing coordinates 
YOrigin Y location of the origin in graphing coordinates 

Hani sh Length of the x-axis in graphing coordinates 

Yeni sh Length of the y-axis in graphing coordinates 

Color Graphing color (usually white) 

NunSegsX Number of segments on the x-axis. This number is one 


Jess than the number of primary ticks marks; if there are 
no tick marks, NumSegsX is zero. 


NunSegs¥ Number of segments on the y-axis 

SubTi cksX Number of secondary tick marks between each pair of, 
primary tick marks on the x-axis 

SubTicksY Number of secondary tick marks on the y-axis 

Lowest Smallest value of X in the data file 

Highestx Largest value of X in the data file 

Lowest Smallest value of Y in the data file 


Highest Largest value of ¥ in the data file 
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Unused Placeholder for unneeded arguments in Stats 
LoXAxis Value for the left end of the x-axis 

HixAxis Value for the right end of the x-axis 

LoYAxis Value for the bottom of the y-axis 

HIYAxis Value for the top of the y-axis 

Scalex Scaling factor used to compute X in graphing units 
Sealey Scaling factor used to compute Y in graphing units 
CharFlag Character value returned by GetNuaR and GetNun! 


Reply, Reply2 Character values returned by KeyHit 


RealFormatX boolean flag indicating whether the x-axis should be 
labeled with real numbers 


RealFormatY boolean flag indicating whether the y-axis should be 
labeled with real numbers 


mid boolean flag indicating whether the annotations should be 
centered on the tick marks or between them 


Discussion 


You may have to adjust the input parameters a few times so that you can create 
the best-looking graph. Usually the tick mark annotations are too crowded (oF too 
sparse) the first time you try a new graph. Although XYGraph centers all annotations 
the best it can, you may want to extend or shrink the length of one or both axes 
to cause the annotations to line up perfectly. 


‘The creation of a pleasing graph is often an iterative process. You try one set of 
specifications and then adjust them to improve readability and aesthetics. XYGraph 
uses several variables to control the appearance of the graph, A dialogue with the 
‘user is a natural way to set these variables. However, the process can get tedious, 
‘especially if you want to rerun the program with one or two changes in order to 
fine-tune your graph. A compromise, therefore, was adopted. Most variables are set 
explicitly to default values, and the dialogue is restricted to the more essential 
variables. 


You may want to remove the input dialogue completely, and simply set values for 
the necessary parameters explicitly, (Modification 9 explains how to do this.) Then 
you can adjust any stubborn variables before recompiling and rerunning the pro- 
‘gram. You might use two versions of this program: the regular version the first time 
you try a graph, and the modified version to hone it 
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Producing a graph of an analytic function is a simple task. Use the Save2Arr sub- 
program in Chapter 6 to create a disk file of the X and Y data produced by your 
function. XYGraph can then plot the graph. 


Modifications 


1, RowSize controls the maximum number of data pairs allowed in your 
disk file. Increase RowSize if necessary. 


2. MaxNumAxisfinn is the maximum number of tick mark annotations 
allowed on one axis. A practical limit for this number is 20. You may 
want to lower the default value to save memory. 

3, Origin and YOrigin control the location of the graph origin on your 
screen. Adjust these variables if you want to move the whole graph 
orthogonally. 

4, XAwisL and YAxisL control the length of each axis. Adjust them to 
change the size of the graph. 

5. Color determines the color used to plot the high-resolution graphics. 


Color must be an integer from 0 to 15, or you can use Turbo's 
predefined color constants. (See the Turbo manual. ) 


6. If you want integer numbers (no decimal points) to be used for either 
axis annotation, change RealFormatX or RealFormatY to false as 
appropriate. 


7. SubTicksX controls the number of secondary tick marks to be placed 
between each pair of primary tick marks on the x-axis. (If no primary 
tick marks are used, SubT1 cksX is irrelevant, ) Similarly, SubTicksY 
controls the number of secondary tick marks on the y-axis. Adjust these 
variables as needed. 


‘8. If your data is already sorted on X, you can remove the two statements 
indicated by (Mod. #8) to save computation time. You may also want to 
remove them if you want unsorted data to stay that way. 


9. To remove the input dialogue (see the Discussion section), you can 
delete (or comment out) all the statements between the two lines 
denoted by (Hod. #9). However, you must replace these lines with 
statements that explicitly set values for LoXAxis, HixAxis, NunSegsX, 
XTextfrr, LoYAxis, HIYAxts, NusSegsY, and YTextArr. 


10. If you want to create a medium-resolution graph, change the hires 
statement to graphaode or graphcolormode. If you make this change, you 
need to set color, palette, and graphbackground compatibly. 
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BarChart 


Purpose: To draw a bar chart on the screen 














Usage 

A bar chart is an effective presentation tool for many kinds of business data. Such 
a chart is especially good for showing time-varying quantities—for example, sales, 
number of employees, or production capacities—per time period. BarChart pro- 
‘vides this charting capability. 

‘The data must be stored in a disk file. The file contains the Y value for each bar 
in the chart, (This Y value determines the height of the bar.) You can use the 
subprogram SaveArr (Chapter 6) to create this file. See the Discussion section. 


First, BarChart prompts you for the filespec of the disk file containing the Y data, 
‘The program assumes that the bottom of each bar is at Y = 0, (That is, the horizon- 
tal axis of the chart is along the line Y = 0.) Values in the data file should not 
be negative. The bars are graphed vertically upward and represent positive values 
of Y. 


You are then shown the largest value of ¥ read from the disk file. This value enables 
you to make a sensible choice for Y at the top of the vertical axis, Make sure that 
you select a value at least as lange as the actual maximum Y. Your input value must 
be an integer, (It is therefore limited to 32767. See the Modifications section. ) 


Next, you must provide the number of primary tick marks to be placed on the 
y-axis, This number must be an integer greater than or equal to zero. If you supply 
0 oF 1, no tick marks are drawn. Otherwise, one tick mark is placed at each end 
ofthe axis, and the other tick marks, if any, are equally spaced in between, Secondary 
tick marks are provided automatically between the primary tick marks, Last, you 
must provide the label for the whole axis. If you prefer, you can press the Enter 
key to eliminate the label completely 


Now the annotation for the x-axis is required. Tick marks for this axis are auto- 
matically generated by the program because the number of bars is already deter- 
‘mined. If you want the spaces between these tick marks to be annotated, you must 
create a disk file containing these annotations, Use SaveTxt (Chapter 6) to create 
is file. (See the Discussion section. ) BarChart asks you for the name of the file. 
If you do not have this file (and thus do not want such annotations), simply press 
the Enter key. Finally, you must provide the label for the whole axis. Again, you 
can press Enter to nullify the label. 





You have six choices for the shading style to be used in the bars, Try each one to 
determine the most pleasing choice for your graph. 
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When prompted, simply press any key to produce the chart on the screen. The 
chart is drawn in high-resolution graphics with white lines on a black background. 
‘Axis labeling and centering are done automatically. After viewing the graph, press 
any key to clear the screen, return to text mode, and end the program. 


Sample Output 


Consider a sporting goods company that manufactures self-contained home gym- 
nasiums. The company wants to analyze its month-by-month sales. A disk file named 
UNITSDTA contains the number of units sold during cach month of 1986, This 
file was created with SaveArr. A string data file called MONTHS.TXT contains the 
‘abbreviations for each of the 12 months; the abbreviations are used as annotations 
on the xaxis. Figures 18.22 and 18.23 show the data entry phase of BarChart for 
this run, The resultant bar chart is shown in figure 18.24. (This figure was created 
on an EPSON printer by using Shift-PriSc with GRAPHICS.COM to get an image of 





the screen.) 

BarChart - Create bar charts 

The input date must be on a disk #11 
Enter filespec of input file, or 

44 press (Enter) key to cancel. “ 

UNITS86. DTA 

19 12 elements now in array. #6 


Y value at bottom of axis ts met to 0 





Largest value in data file = 4,552000€¢05 


¥ value at top of avis? (integer please) 
Entry 





Number of primary tick marke on y-axis? 


Entry? & 


Label for y-axis 
> Unite Sold 


Fig, 18.22. Roading the data fle and specifying the yauxis 
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Variables 
ArraySize 
Num@rray 
TempTextArr 


XTextarr 


Maximum number of data values (bars) allowed 
Array containing the input data read from disk 


Array containing the string data for the X tick mark 
labeling. This data is read from disk. 

string array of the annotations for the x-axis. The zero 
‘element contains the label for the whole axis, The 
‘elements from 1 upward contain the labels for the spaces 
between the primary tick marks. These (positive valued) 
elements are identical to those in TempTextfrr. 
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YTextarr string array of the annotations for the y-axis 

Origin X location of the origin in graphing coordinates 

YOrigin Y location of the origin in graphing coordinates 

XAxisL. Length of the x-axis in graphing coordinates 

Yaxist. Length of the y-axis in graphing coordinates 

Color Graphing color (usually white) 

SubTicksk Number of secondary tick marks (usually 0) between each 
air of primary tick marks on the x-axis 

SubTicksY Number of secondary tick marks on the y-axis 

Count Number of data values in NunArray 

Code Return code from Load@rr and GetNual 

TextCount Number of data values in TeapTextArr 

LoYAnis Value (usually 0) for the bottom of the y-axis 

HIYAKLs Value for the top of the y-axis 

NumSegsX Number of segments on the x-axis. This number is the 
same as the number of bars in the chart. 

NunSegsY Number of segments on the y-axis. This number is one 
less than the number of primary tick marks; if there are no 
tick marks, NunSegsY is zero, 

UpLertx X graph coordinate of upper left comer of a bar 

Uplerty Y graph coordinate of upper left comer of a bar 

LoRi ghtx X graph coordinate of lower right comer of a bar 

LoRi ght¥ Y graph coordinate of lower right comer of a bar 

ShadingType Type of shading to use in cach bar (0 = none, 1 = filled, 
2 = horizontal, 3 = vertical, 4 = diagonal, 5 = herringbone) 

Density Amount of space between shading lines 

FlipFlop Shading indicator—alternating shading if positive, constant 
shading if 0 

J Looping index 

NuaTicks Number of tick marks on axis 

Unused Placeholder for unneeded arguments in Stats 
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Lowest Smallest Y value in data file 

HighestY Largest Y value in data file 

Uiathx Width of a bar in graph coordinates 

ScaleY Scaling factor used to compute Y in graphing units 
CharFlag Character value returned by GetNual 


Reply, Reply2 Character values returned by KeyHit 


RealFormaty boolean flag indicating whether the y-axis should be 
annotated with real (or integer) numbers 


Midx, MidY boolean flags indicating whether the x-axis and y-axis 
annotations should be centered on the tick marks or 
between them 

Discussion 


‘As with X¥Graph, the creation of a bar chart is frequently an iterative process. You 
need to try different shadings and labeling to find the most pleasing and effective 
chart. 


‘Typically, the data for each bar chart is created externally in another program. The 
SaveArr subprogram is ideal for creating the disk file once the data is saved in an 
array. This array should have the Y value for the first bar in element 1, the Y value 
for the second bar in element 2, and so on. SaveArr can then put the data se- 
‘quentially on disk in exactly the form needed by BarChart. 


If you prefer, you can specify the data explicitly in BarChart. You must replace the 
LoadArr statement with code that stores the data into Numfrray directly. Then set 
Count equal to the number of data values present 


Similarly, the string data for the bar labeling on the x-axis is expected to be in a 
disk file. You can use SaveTxt to create this file. The text strings in this file should 
directly correspond with the data values in Nuafrray. Again, you can set these strings 
‘explicitly in BarChart by filling TempTextArr through direct assignment statements, 
Remove the LoadTxt statement if you take this action. 





Modifications 


1. ArraySize controls the maximum number of data values allowed in your 
disk file. Increase the value of this variable if necessary 


2. XOrigin and YOrigin control the location of the chart origin on your 
screen. Adjust these variables to move the whole chart orthogonally 
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XAxisL and YAxisL control the length of each axis. Adjust them to 
change the size of the chart. 


. Color determines the color used for the high-resolution graphics. Color 


must be an integer from 0 to 15, or you can use Turbo's predefined 
color constants. (See the Turbo manual.) 


‘The program is now restricted to integer constants for the tick mark 
labeling on the y-axis. If you want to use real numbers (to accommodate 
values larger than 32767), change RealFormatY to true. In addition, the 
GetNunl call (at the line denoted by (Hod. #5)) must be replaced by 

GetNuaR. You must also add GetNuaR to the list of included subprograms. 


SubTicksX controls the number of secondary tick marks to be placed 
between each pair of primary tick marks on the xaxis. This number is 
typically 0, indicating no secondary tick marks. But you can have them if 
you want. Similarly, SubTicksY is the number of secondary tick marks on 
the yaxis, You may want to adjust these variables. 


LoYAxis is the value of ¥ to use as the base of each bar, This value is 
‘usually 0, but you may adjust the value. 


Density controls the density of the shading, Adjust this variable to alter 
the number of shading lines in cach bar. 


‘To enhance the graphics effect, you can alternate the shading used in 
consecutive bars, First, determine the two integer values of ShadingType 
for the two kinds of shading you want to alternate. Second, replace the 
three lines denoted by (Hod. #18) with two statements like the 
following: 

ShadingType == 4; 

FlipFlop == 2, 
The value assigned to ShadingType is the higher of the two integer 
values specifying the shading types. The value assigned to FlipFlop is 
the positive difference between the two integer values. 
If you want to create a medium-resolution graph, change the hires 
statement to graphaode or graphcolormode. If you make this change, you 
ced to set color, palette, and graphbackground compatibly. 


A 





How To Create and Use 
a Subprogram Library 





To use a subprogram from this book, you need to type accurately the subprogram 
into your computer, save the subprogram on disk, and compile the subprogram as 
part of a larger main program. (‘The main program may be one of the Sample Usage 
programs accompanying cach subprogram, a full program from Chapter 18, or an 
original program of your own.) You can organize your subprogram and program 
disk files in many ways. This appendix presents an approach for entering, saving, 
and testing these subprograms, thus creating an easy-to-use subprogram library on 
disk, 

‘We assume that you have an IBM PC (or compatible) with two floppy disk drives 
(or one floppy disk and one fixed disk), and that you are running PC DOS (or MS- 
DOS) Version 2.0 of higher with Turbo Pascal Version 3.01A. Changes may be 
necessary for other configurations. We assume also that you are typing the sub: 
programs yourself, A much better idea (though more expensive) is to use the 
associated disk with all the subprograms and programs from this book. This disk 
is available for purchase separately. If you have the disk, refer instead to the in- 
structions accompanying it 


In addition, we assume that you are sufficiently familiar with Turbo Pascal to start 
it up, use the Turbo editor to enter and change a program, and compile and run 
the program. For the discussion that follows, we assume that you have a copy of 
the Turbo compiler disk in floppy disk drive A and a data disk in drive B, We'll 
discuss fixed disk systems, but you may need to make adjustments depending on 
how you installed Turbo and what subdirectories you use. 





Starting Turbo Pascal 
Start Turbo Pascal, respond with Y to include error messages or N if you don’t 
want such messages (we recommend Y), and use the L command to make B the 
logged (default) disk drive. For a fixed disk system, you probably need to make C 
the logged disk drive and then use the A command to set the active directory; let's 
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assume that TURBO is the subdirectory you use for all Turbo Pascal files. For floppy 
disk systems, let's assume for now that you do not use subdirectories. 





Entering a Subprogram 


Select a subprogram from this book. We'll use ShouTime as an example. Enter the 
W command and respond with the work file name ShouTime. PSL, All subprograms 
in this book require the file name extension . PSL for consistency with the associated 
Sample Usage programs, and for the remainder of this discussion to be accurate, 
Note that capitalization is irrelevant in file names. We use capitalization for read- 
ability only. 


Enter the E (edit) command to edit the subprogram. The Turbo editor responds 
by displaying a blank screen with the file name at the top. Type the source code 
for the ShouT ine subprogram extremely carefully. Although spacing is largely op- 
tional in Pascal programs, we strongly recommend that you duplicate our subpro- 
grams exactly as they are shown in the book. This includes spacing, comments, 
blank lines, and capitalization. Deviations make it much harder to check for typing 
errors later. 


When typing, be especially careful that you get all the punctuation characters right 
(semicolons, commias, colons, equal signs, and periods), A missing or added semi- 
colon in the wrong place may not cause a compilation error but can change the 
entire meaning of a Pascal program. In addition, be extremely careful not to confuse 
similar alphabetic and numeric characters when you type. In particular, look out 
for lowercase | (the letter “el”) instead of the number 1 (one), or uppercase 0 
(the letter “oh") instead of the number @ (zero). Another common typing mistake 
is to use incorrect spacing between apostrophes. Pascal uses apostrophes to define 
character strings. In some subprograms and programs, you must type the number 
of spaces between apostrophes in an exact way in order for the program to work 
correctly. Often the number of spaces is zero; don't put a space between the apos- 
trophes unless you see a space in the book. 


After typing the complete subprogram, enter the Ctrl-K-D sequence (press the K 
key while holding down the Ctrl key and then press the D key) to end editing, 
‘Then enter the S command to save the subprogram on disk. 


Typing a Sample Usage Program 
Now you are ready to type the Sample Usage program that accompanies the sub- 
program. This short program demonstrates how the subprogram works, and pro- 
vides a way to verify that you typed the subprogram correctly. Once again, use the 
W command to select 4 work file name. This time use the name ShowTime. SU for 
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the file. The SU stands for Sample Usage and is our way of keeping the sample 
program distinguished from the subprogram yet still relating the two. 


Enter the E command and then type the Sample Usage program from the book. 
Again, be extremely careful to type the program exactly as it is shown. When you 
have finished typing the program, enter the Ctrl-K-D sequence to end the edit, and 
then enter the S command to save the program on disk. 


Testing the Subprogram 
with the Sample Program 


‘The moment of truth is at hand. Enter the C command to compile the subprogram, 
This causes the Sample Usage program (still designated as the work file) to be 
compiled. During the compilation the subprogram is drawn into memory from disk 
by the ($1 ShouT ime. PSL) statement in the Sample Usige program, The program 
and the subprogram compile together. If there is an error in either the Sample 
Usage program or the subprogram, the compiler displays an error number and 
‘message (unless you responded with N when starting Turbo ) and tells you to press 
the Esc key to continue. After you press the Esc key, Turbo indicates the place in 
the subprogram or program where an error is detected. 


Usually the cause is a typing error in that line or the one immediately before it, If 
$0, correct the error, end edit with Ctrl-K-D, save the revised file with the $ com: 
mand, and recompile with the C command. You may need to use the W command 
first 10 make the Sample Usage program the work file again. If the error is in the 
subprogram, Turbo automatically makes the subprogram the work file (so that you 
‘can make corrections). 


Be aware that Turbo may report an error in one line when the actual typing error 
is in a previous line. If you get a compiler error and can't find the typing error 
that caused it, refer to Appendix B. A typing error in the subprogram may even 
cause Turbo to tell you that the error is in the Sample Usage program. If all else 
fails, you may need to search through every line, character by character, of both 
the subprogram and the Sample Usage program, looking for typing errors 

Eventually, all your typing errors will be fixed. (For all you infallible typists who 
always get “clean” compiles the first time, we applaud you. You are a small mi- 
nority.) The result of an error-free compilation is three lines on the screen showing 
how much memory is required by the program. Enter the R command to run the 
program. You should see on the screen a duplication of the sample output shown 
or described in the book. For some subprograms, such as ShouTime, your output 
‘will be slightly different, ShouTiae shows the current time of day, and the time of 
day when you run your test is unlikely to match exactly the time shown in the 
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book. Other sample programs require that you enter data. If so, enter the same 
data shown in the sample to see whether you get the sume results. 


If your sample program output matches the output shown in the book, you can 
be fairly confident that you typed the subprogram (and Sample Usage program) 
correctly. You can't be completely confident because a short test program can't 
{est all possible subprogram conditions. Modify the Sample Usage program to check 
other conditions if appropriate. 

If you see unexplained differences between your output and the sample output in 
the book, reread the subprogram explanation to be sure that you understand what 
the subprogram is supposed to do. If you still can’t explain the discrepancies, check 
‘once more for typing errors. If that fails, refer to Appendix B. 


Building Up a Subprogram Library 


‘Once you have one subprogram working, go back and begin the process again with 
another subprogram. Continue entering and testing the subprograms until you have 
built up the complete library or the subset appropriate for your nceds. Two prob: 
Jems arise as you build up a substantial subprogram library if you have a system 
with two floppy disks. Neither problem affects the fixed disk system owner. 


First, the root directory of a 360K floppy disk has room for only 112 file names, 
but you will create over 200 files if you enter all the code in this book (subprograms, 
Sample Usage programs, and full programs). The simplest solution is to create a 
subdirectory on your data disk and store all your files in the subdirectory instead 
of the root directory. Subdirectories do not have a limit of 112 file names. To create 
the subdirectory, use the DOS command MKDIR. If you are not familiar with sub- 
directories, see your DOS manual. Suppose that you decide to use the subdirectory 
‘name TPPL for the Turbo Pascal Program Library. Once you create the subdirectory, 
simply use the A command whenever you start Turbo to indicate that the active 
directory you want is \TPPL. That way, the 112-file limit will not be a problem. 


‘The second problem on a system with two floppy disks is lack of disk space. All 
the subprograms, Sample Usage programs, and full programs fit on one 360K disk 
with little room to spare. This lack of space can be a problem if you want to do 
more program development with the subprogram library. The solution is to create 
a new data disk, create a subdirectory on the disk as just discussed, and copy all 
the subprogram files (named with extension . PSL) from the full disk to the new 
fone. If you use the subdirectory name TPPL on both disks, you can easily copy all 
the subprogram files with a single DOS command because of our recommended 
file names. Use the following command: 


COPY A\TPPL\*.PSL_B:\TPPL 
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Of course, your data disk containing all the subprograms must be in drive A, and 
your new data disk must be in drive B when you enter this command. After the 
copying is complete, you will have a data disk with all the necessary subprograms 
available on a disk, with room for more program development. The subprograms 
themselves occupy less than half the space of a 360K disk. Depending on your 
needs, you may want to copy only some of the subprograms, giving you even more 
room to work. 


Entering and Running the Full Programs 


Chapter 18 contains several full programs. These complete programs demonstrate 
the methodology of including numerous subprograms in a main program. Enter a 
full program the same way you enter a Sample Usage program, except give the 
‘work file name an extension of . POH, identifying the file as a full program from 
Chapter 18, Each full program requires several subprograms, as explained in the 
chapter, Be sure that you have entered (and saved on disk) all the necessary sub- 
programs before you try to run a full program. 
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B 


What To Do If You Have Problems 








‘We can't possibly anticipate every kind of problem you may encounter, but here 
are some steps to take when things go wrong. 


1. Read Appendix A. 


Appendix A explains the general procedures for entering, saving, and testing the 
subprograms. If you don’t understand the procedures, or if you don’t understand 
their intent, you may need to do some more studying before continuing with this 
book. If you have trouble entering, editing, compiling, and running programs, read 
the Turbo Pascal Reference Manual or an introductory Turbo Pascal book. If you 
don't understand subdirectories or DOS commands, read the documentation that 
‘came with DOS or a tutorial book about DOS. 


2. Read about the subprogram or full program. 


‘Your problem may be that you don't understand how the subprogram or full pro- 
gram is supposed to work. Reread the explanation of the subprogram or program 
that is causing the problem. Read the enttire explanation. Many tips are contained 
in the Limitations and Error Conditions section, the Discussion section, and the 
‘chapter introduction. Don’t make assumptions about how you think the subprogram 
should work. Be sure that you define all the input and output variables correctly. 


3. Check your typing. 
We can't emphasize this point cnough. If you know the fundamentals of dealing 
with Turbo Pascal and DOS (as explained in step 1), and if you have read and 
understood the subprogram explanation, your problem is almost certainly a typing 
error, Yes, we admit the possibility that the error may be in our programming, 
(Refer to the Reader Feedback section near the end of the book.) But we have 
tested these subprograms, and you should nor be getting certain types of errors 
unless some sort of production error occurred in printing this book. Almost cer- 
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tainly, your typing error will cause a compiler error message or a run-time error 
when you try to duplicate the output from the Sample Usage program. 

Review the typing tips in Appendix A. Look for punctuation errors—that missing 
‘of extra semicolon, the parentheses instead of square brackets or braces, or the 
missing apostrophe. Check that all of those 1's aren't lowercase I's, and that you 
haven't confused capital O's with zeros. Look for that line you may have omitted 
entirely. Carefully recheck every character on every line. Often it is helpful to print 
‘out what you have typed and then compare the printed listing with what is in the 
book. Don't limit your search to the line that Turbo says has an error. A typing 
error in one line can often cause an error message in another, These “remote” 
errors may occur if you omit a begin or end statement, a right brace (thus turning 
a whole chunk of a program into a comment), or an apostrophe. If you can't find 
an error in your typing, ask a “nitpicking” friend to look for you, 


Remember, if a subprogrim doesn’t work, assume that you have made a typing error 
until you prove otherwise. 


4, Document the problem, 


‘What if there really is a bug in a subprogram? Well, we want to fix it. If you are 
absolutely sure that you have not made any typing errors (please check one more 
time), then put together all the information you can about the problem and let us 
know. We'll be very appreciative. Our address is in the Reader Feedback section 
near the back of the book. Mentioned also in that section are specific things we 
‘want from you in explaining the problem. If you really did find a problem, we'll 
refund the dollar you send us. And if you are the first to find the problem, we'll 
probably even send you an extra dollar (one we received from a bad typist who 
thought he/she found an error). 


GC 


Programming Style and Conventions 








As Long As It Works, 
Who Cares What It Looks Like? 


Nothing seems to engender as much passionate partisanship among Pascal pro- 
‘grammers as questions of programming style. For some reason, two seemingly in- 
telligent, sane Pascallers [sic] can argue for hours about semicolons and where to 
put an else, 


Perhaps the problem arises because of the freedom Pascal allows in program style. 
Pascal embraces a strange contradiction because the language is quite rigid in some 
‘ways yet extremely flexible in others. Pascal compilers insist that each variable be 
predeclared and assigned a specific type. Semantic meaning is rigorous, However, 
names are free-form, block structure is open, and many ways to do the same thing 
are available, Pascal is something like a piano. There are only a certain number of 
keys to play, but the ways you can play them and the music you can create are 
boundless. 


Surprisingly, there is little agreement about what a Pascal program should actually 
look like, Most authorities agree that programs should consist of clean, modular 
units and should be organized in a top-down structure. But what about more mun- 
dane issues? Have you ever considered where to put the begin and end statements 
in a small coding block? Consider this code fragment 





1f BigDeal then 
begin 
uriteln(’ This is our style’); 
futhort ©= “Rugg; 
futhor2 := ’Feldean 
end 
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In the literature, respected authorities write this type of construct in several ways. 
‘The begin might be flush with the 1f or on the same line with then. The end could 
be in any of several places: indented parallel to the if, parallel to Author2, or on 
the same line with Fel dnan, 


Coding Conventions 


Programs in many popular Pascal textbooks use various coding conventions, Often 
there is little consistency within the same book—not that there is only one way 
to do things or that uniformity is always 2 virtue. We must remain masters of our 
tools, not slaves to them. Unabashedly, we have developed our own set of coding 
‘conventions. When there is good reason to override them, we do so—but sparingly. 


For increased legibility, all Turbo Pascal reserved words, subprograms, full programs, 
and subprogram and program excerpts appear in Digital font 


Capitalization 


‘Turbo reserved words (sce Appendix E) are in lowercase. These are Turbo's key- 
words—the predefined identifier names such as program, true, for, writeln, pi, 
integer, and so on. 


Identifier names we create (subprogram names, variables, type names, etc.) always 
begin with a capital letter, Furthermore, capital letters are used freely within the 
ame to increase readability. Examples of names we create are GetReply, ArrayType, 
and Code. 


‘The sole exceptions to these capitalization rules (why are there always exceptions?) 
are the single BEGIN and the single END. that delimit the executable part of a main 
program (not a subprogram). Those two words appear in uppercase. Any other 
begin and end appear in lowercase, as expected. (These exceptions help set off 
the main block of a program from the subordinate blocks.) 


Names for Subprograms and Programs 


Each subprogram has a name limited to cight characters. This limit ensures that 
the subprogram can be saved with that same name on an IBM PC disk. When a 
Subprogram name is saved on disk, the file suffix PSL is used. 


Names of full programs in Chapter 18 are also limited to eight characters for the 
same reason. Here, however, the extension . PGH is added when a full program is 
saved on disk. 





APPENDIX C 293 





Variable Names 


Many of our subprograms are designed for compatibility with one another. Variable 
names are identical across subprograms whenever possible. In addition, variables 
in the main part of Sample Usage programs are usually given the same names as 
those of their counterparts in the subprograms. (That is, the actual parameter list 
in a statement invoking a subprogram is usually the same as the formal parameter 
list in the subprogram header.) This convention is used for case of reference. 


Semicolons 


In Pascal the semicolon is a statement separator, not a terminator, Consider the 
following: 





for J == 1 to S do 
begin 
Count :* Count + NusfrrayCJ3;, 
uriteln(J, NumArrayCJ2), 
end 
‘The last semicolon (in the line with writen) is unnecessary. (Putting the semi- 
colon there creates a blank statement between the semicolon and end.) We have 
avoided these superfluous semicolons. The same goes for the last line before unt 1 
and other similar Pascal constructs. Note that keywords like end, else, and unt! 
fare statement delimiters, not statements themselves. Thus, 1 semicolon is never 
required just before end or another delimiter. 


Indentation and Rightward Creep 


Indentation sets off block structure and makes a Pascal program much easier to 
read and understand. We use indentation liberally. Unfortunately, because of nested 
blocking, some programs seem to drift doggedly toward the right. (This problem 
is especially acute to us since we can't put any code past the 65th column position, 
as explained shortly.) Here is what we tried to do (occasionally we had to 
compromise ): 


© Indent new subblocks three characters from the previous block 


© Place begin and end on distinct lines indented from the previous block 
‘© Keep paired begin and end at the same indentation level 
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If. Then..Else 


Our preferred form is as follows: 





if Done then 
writeln(’All data processed’ ) 
else 
begin 
Count = Count + 4; 
uriteln(’Still more to do’) 
end, 
uriteln(’ This 1s the next statement’ ); 


‘The object phrases of then and else are indented. The else, if it appears, is on a 
sepirate line at the same indentation level as that of the corresponding 1f. 


A similar form is used for repeat.until and other delimited statements. 


Alignment and Split Lines 
Writing a book puts pressure on a coding style. For purposes of reproduction in 
the book, line lengths are limited horizontally. The maximum number of characters 
‘on any program line is 65. Therefore, program statements must be broken in half 
much more often than normal. 


When a single, logical line has to be broken in half (because it extends past position 
65), we try to split it at a convenient identifier name and indent the continuation 
part several characters (at least 5) from the initial part. This convention maximizes 
readability. 


When several consecutive lines contain assignment statements, we try to align the 

= operator at the same tab position if at all reasonable. This convention is also 
‘true for equal signs in consecutive type declarations, colon separators in var blocks, 
and other similar constructs. 


Spacing 
‘One space is put on either side of each operator symbol. Examples of operators 
are +, -, '*, >, and or. 


If the colons are aligned in a var block, a space is put on either side of the colon. 
If the colons are not aligned, however, a space still appears after the colon, but 
‘no space appears before the colon. 


One space is used after each comma, colon, and semicolon. The exceptions are 
these: no space after a comma in a multiple subscript reference, and two spaces 
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after a semicolon if multiple statements appear on the same line, Rarely does more 
than one statement appear on the same line 


Ordering of the Program Parts 


Unlike other Pascals, Turbo allows considerable flexibility in the declaration of the 
main program parts. Here, we are speaking of the label, const, type, and var 
sections. Turbo allows these sections to appear in any order, and the language even 
allows more than one section of a given kind. We have stayed with the nominal 
Pascal standard: one declaration of each part, if any, and always in the order just 
shown. In a full program, procedures and functions follow these declarations, and 
the executable part of the main program comes last. 


Comments 


Although all programs and subprograms are well documented in the book, com: 
‘ments in the source code have been kept to 4 minimum to discourage distribution 
of the programs to those without this book. 
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D 





The Environment for 
Turbo Pascal Timings 





In this book, we refer to the amount of time required to run a Turbo Pascal program. 
Many factors can affect program timings. This appendix describes the methodology 
and equipment we used. 


All timings were done on a standard IBM Personal Computer running PC DOS V2.0. 
‘There were no unusual peripherals, hardware modifications, or software modifi- 
cations that would have any effect on the speed of the runs. 


‘The version of Turbo Pascal we used was 3.014. All the default compiler directives 
were in effect. You should be aware that some of the compiler directives, such as 
(SR+) and (SU+) can greatly change the speed at which programs run, 


We used the PC’s internal clock to make the timings, accessing the clock with the 
ShouTime or GetTime subprograms. In some cases (such as the searching subpro: 
grams), we had to repeat a subprogram many times (100 oF 1,000) and divide by 
the number of repetitions in order to determine the time required to execute a 
fast subprogram once. We have rounded the timings to match the approximate 
precision of the clock. See GetTime (Chapter 17) for details about the clock’s 
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E 





Reserved Words in Turbo Pascal 





‘The following is a list of reserved words in Turbo Pascal Version 3.01A for the 
IBM PC. ‘The lists in the Turbo manual are incomplete. Avoid using any of the 
following words as a variable or subprogram name. Words from extended graphics 
and turtlegraphics are excluded 


abs 
absolute 
addr 

and 
append 
arctan 
array 
assign 
aux 
auxinptr 
auxoutptr 
begin 
black 
blink 
blockread 
blockwrite 
blue 
boolean 
brown 
buflen 
bude 
bus 

byte 

49 

88 


case 
cbreak 
chain 
char 
chdir 
chr 
close 
clreol 
clrser 
con 
concat 
coninptr 
conoutptr 
const 
constptr 
copy 

cos 
ertexit 
ertinit 
seg 
cyan 
darkgray 
delay 
delete 
delline 


dispose 
div 

do 
dounto 
draw 
309 
else 

end 

cof 

eoln 
erase 
errorptr 
execute 
exit 

exp 
external 
false 
file 
Filepos 
filesize 
Fillebar 
flush 
for 
forward 
frac 


freeones 

function 

getdir 
tao 





goto 
gotoxy 
graphbackground 
graphcolormede 
graphaode 
graphwindow 
green 

halt 

heapptr 

ht 

highvideo 
hires 
hirescolor 

if 

in 

inline 

input 

insert 

insl ine 

int 

integer 


intr 
foresult 

kbd 
keypressed 
label 

Jength 
Hightblue 
Lighteyan 
Lightoray 
lightgreen 
Lightmagenta 
Lightred 

In 

lo 

longf {lepos 
longfilesize 
Jongseek 
Jowwideo 

Ist 
Istoutptr 
magenta 

mark 
maxavail 
maxint 

en 
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memavai | 
nam 
mkdir 
mod 

ove 
sdos 
new 

ail 
normvideo 
‘nosound 
not 

odd 

of 

ofs 

or 

ord 
output 
overlay 
ovrpath 
packed 


palette 
paramcount 
paramstr 
pi 

plot 

port 
portu 

pos 

pred 
procedure: 
program 
ptr 
random 
randosize 
read 
readin 
real 
record 
red 
release 
rename 


repeat 
reset 
reurite 
radir 
round 
seek 
seckeof 
seekeoln 
309 
set 
shi 
she 
sin 
sizeof 
sound 
sor 
sort 
3509 
str 
string 
suce 


swap while 
text white 
textbackground window 
texteolor vith 
textaode write 
then writeln 
to or 

tra yellow 
true 

trune 

truncate 

type 

until 

vupcase 

usr 

usringtr 

usroutptr 








Reader Feedback 





We welcome your feedback about this book. In particular, we welcome comments 
about (and improvements to) the subprograms themselves. We hope that interest 
will be high enough to call for a second volume. It could contain many more useful 
subprograms. 

If you have developed a handy subprogram, or if you have suggestions about what 
kind of subprograms you would like to see in Volume 2, please let us know. If you 
send us a subprogram listing, by doing so you are agrecing to let us publish it if 
we choose to, and you are certifying that the subprogram is your original work, 
No plagiarism, please. We may use the subprogram as is, modify it, or ignore it. 
We'll also feel free to acknowledge you by name unless you plead for anonymity, 
In all cases, we'll be grateful. Please be aware that we are most interested in short, 
clearly written subprograms that are potentially interesting to a wide variety of 
people. 


{As for the book you now hold, we recognize that some errors may exist, We have 
carefully tested the subprograms, Sample Usige programs, and full programs, but 
some errors may have slipped through nevertheless. We take no responsibility for 
any damage you may suffer because of programming errors. You must bear the 
responsibility of testing all programming thoroughly in your own environment be- 
fore making assumptions about accuracy. 


If, however, we find errors in programming or ambiguities in explanations, we want 
you to have the opportunity to find out about corrections. We will accumulate an 
‘errata list that you can send for AS mentioned previously, we also welcome your 
corrections if you find errors. Our past experience with software hooks has taught 
Us that many readers write to us with scrawled letters much like this: 


1 typped inn you're ShowTim porgram and it does'nt work. 
Please send me the correctoins 


‘This is worse than most letters—but not all of them, Please be aware of a few facts 
before you write to us: 


1, If a program in this book won't work for you, the overwhelming 
probability is that you have made typing errors. We are continually 
amazed at how many readers swear that they have rechecked their 
typing 5 (or 8 or 13) times and are positive that they have no errors. 
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Yet when we ask them to send us a printed listing of what they have 
typed, we immediately find numerous typing errors. The lesson is this: If 
you are not good at proofreading what you have typed (and many 
intelligent people are not), find a good proofreading friend to check 
your typing for you. If you send us a letter with numerous typing errors 
in it, your credibility as an accurate typist will not be high. 


‘Once you are sure that your typing is accurate, read both Appendix A 
and Appendix B to be certain that you have done everything possible to 
find and fix the error. And reread the explanation of the subprogram (or 
full program) to make sure that you understand what the program is 
actually supposed to do. Don't complain to us because ShouTime doesn’t 
gong 12 times at midnight. 


Finally, if you write to claim that a program doesn’t work, be sure to 
document exactly what you mean. We can't help you if we can't 
understand the problem. Be sure to send all of the following: 


4. A self-addressed, stamped envelope. 


b. A printed listing of the subprogram and/or program as you typed it so 
that we can verify your typing accuracy. 


¢. A detailed explanation of exactly what went wrong. Is the error at 

compile time or run time? Is there an error message? If so, exactly 
what is it? Where in the program does Turbo indicate the error is? If 
there is no error message, exactly what goes wrong and when? What 
input did you provide, if any? For example, did the first four lines of 
output match the sumple output in the book, but then the fifth line 
was wrong? What was different? Be specific! Include printed output 
that shows the error if possible. 


4. Information about your computer configuration if it is anything other 
than what is listed in Appendix D. What computer model and what 
version of DOS are you using? What version of Turbo? Are you using 
only the default compiler directives? Which video interface do you 
have? Anything else unusual? 


©. One dollar. Cash is preferred, but send a check if you're paranoid 
about sending cash through the mail 


As you may have concluded by now, our past experience with reader correspon- 
dence has made us cautious. But we still want you to have a chance for help if 
you need it. That's why the dollar is required along with everything else. We want 
you to demonstrate a little sincerity about your efforts to find the error before you 
write to us. Believe us, we don’t make as much money per hour answering these 
letters as we would handing out Big Macs. 
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‘And if you don't want to complain about an error but just want to find out whether 
‘we have discovered any errors for our errata list, write to us and ask for the “TPPL 
Errata” at the following address: 


Rugg and Feldman 
‘TPPL. Errata 

PO, Box 24815 

Los Angeles, CA 90024 


Be sure to include a self-addressed, stamped envelope (or a self-addressed, un- 
stamped envelope if you are writing from another country). We'd also appreciate 
a dollar (or even a quarter) to help cover copying and handling costs, but that's 
up to you. 
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1-2-3 for Business, 2nd Edition . $19.95 
1-2-3 Business Formula Handbook. 219.95 
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save hours of time and effort 


TURBO PASCAL 
PROGRAM LIBRARY DISK 


The entire source code from the book Turbo Pascal Program Library has been put on this disk 
to help you improve your techniques and increase your speed in writing programs in Pascal. Con- 
taining all 124 subprograms, all 124 sample usage programs, and all 10 full programs, this disk 
gives you more time to concentrate on your main program, and eliminates a cause of typing errors. 
‘An outstanding aid for the Pascal programmer. 


only $29.95 IBM PC Format 


Use the order blank below to order your Turbo Pascal Program Library disk today. For more in- 
formation, call Que at 1-800-428-5331 





Mail to: Que Corporation * P.O. Box 50507 * Indianapolis, IN 46250 

















Please send copy(ies) of Turbo Pascal Program Library disk(s) at $29.95 each 
Subtotal $ 
Shipping & handling ($2.50 per item) $ 
Indiana residents add 5% sales tax $ 
TOTAL $ 
Method of Payment: 
Ocheck (Cvisa CiMasterCard C1 American Express 
Card Number Expiration Date 
Cardholder's Name 
Ship To 
Address 
City State zp 





In a hurry? Call 1-800-428-5331 and order TODAY. 
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TURBO PASCAL 
PROGRAM LIBRARY 


Over 100 practical Turbo Pascal® subprograms, the building blocks for your 
finished programs, make up this comprehensive reference book, Turbo 
Pascal Program Library 

Each subprogram is explained in detail and illustrated by a sample program. 
With these subprograms, you can enter data from the keyboard, detect errors, 
produce graphic effects, manipulate disk files, sort data, calculate curve fits, 
do matrix algebra, and perform many other useful tasks. 

Ifyou are a beginner in Pascal, this book gives you practical programming 
tips and program components that you might have trouble developing 
yourself. 

If you are an intermediate or advanced programmer, this book is an instant 
software reference library. Its primary benefits are simplified program 
development and expediency. Using just one of these subprograms justifies 
the cost of the book in the hours saved not developing original code. 

Authors Tom Rugg and Phil Feldman, experts in computer programming for 
over 20 years, will show you how to take advantage of the book's ready- 
made routines so that you can improve your productivity immediately. 

Let the Turbo Pascal Program Library improve your programming 
techniques and productivity in record time. 


